v1

latestOpenAPI 3.1.02026-08-04170116.0 KB

Data In

Create Subscription Record

Ingest subscription data into Triple Whale. This endpoint allows users to upload detailed subscription information, including customer details, items, status, and metadata.

post/data-in/subscriptions

Request body

shopstring required

The exact Shop URL (e.g., 'example.myshopify.com'). Must match the Shop URL value shown in Settings → Store. The API key owner must also have access to the shop, otherwise the request will return 403.

subscription_idstring required

The unique identifier for the subscription.

platformstring

The platform where the subscription was processed.

platform_account_idstring

The account ID associated with the platform. Can be used to segment parts of the data coming from different platform accounts, e.g. facebook_account_a vs. facebook_account_b.

created_atstring date-time required

The time at which the subscription record was created. Must be provided in ISO 8601 format, with explicit timezone information (Z or +/-HH:mm offset). Offsets are supported (e.g., 2024-11-29T12:00:00+02:00).

canceled_atstring date-time

The time the subscription was canceled, if applicable. Must be provided in ISO 8601 format, with explicit timezone information (Z or +/-HH:mm offset). Offsets are supported (e.g., 2024-11-29T12:00:00+02:00).

ended_atstring date-time

The time the subscription ended (canceled or expired), if applicable. Must be provided in ISO 8601 format, with explicit timezone information (Z or +/-HH:mm offset). Offsets are supported (e.g., 2024-11-29T12:00:00+02:00).

cancellation_reasonstring

The reason for the subscription's cancellation.

cancellation_commentsstring

Additional comments regarding the cancellation.

currencystring required

The currency of the subscription (e.g., 'USD').

statusstring required

The status of the subscription (e.g., active, canceled).

metadatastring

Additional metadata or notes related to the subscription.

updated_atstring date-time

The time at which the subscription record was last updated. Must be provided in ISO 8601 format, with explicit timezone information (Z or +/-HH:mm offset). Offsets are supported (e.g., 2024-11-29T12:00:00+02:00). Defaults to the current time.

Example request

{
  "shop": "madisonbraids.myshopify.com",
  "subscription_id": "sub-123",
  "platform": "custom_subscription_platform",
  "platform_account_id": "acct-456",
  "created_at": "2022-06-15T19:26:30.000Z",
  "canceled_at": "2024-12-01T10:00:00Z",
  "ended_at": "2024-12-15T12:00:00Z",
  "cancellation_reason": "Customer Request",
  "cancellation_comments": "Dissatisfaction with service.",
  "currency": "USD",
  "customer": {
    "id": "cust-789",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "first_name": "John",
    "last_name": "Doe"
  },
  "subscription_items": [
    {
      "subscription_item_id": "sub-item-001",
      "created_at": "2022-06-15T19:26:30.000Z",
      "canceled_at": "2024-12-01T10:00:00Z",
      "ended_at": "2024-12-15T12:00:00Z",
      "status": "active",
      "interval": "month",
      "interval_count": 1,
      "product_id": "prod-123",
      "price": 19.99,
      "quantity": 1,
      "variant_id": "variant-123",
      "discount": {
        "amount_off": 5,
        "percent_off": 10
      }
    }
  ],
  "status": "active",
  "metadata": "Preferred customer",
  "updated_at": "2024-11-29T10:00:00Z"
}

Response

Subscription record successfully received.

successboolean

messagestring

Example response

{
  "success": true,
  "message": "Subscription received"
}