Why Use Stay Ai Open APIs?

Well that's easy. Stay Ai Open APIs allow you to programmatically access data stored in Stay Ai. We are well aware that no matter how awesome our product is, every merchant has different needs. Using our APIs allows you to create dashboards, pull reports, or build functionality with Stay Ai's data, but catered to your requirements. The world (and the subscription data within it) is officially your oyster!

Getting Started

Create API Keys

Let's connect! Take the first step to using Stay Ai's Open API by creating API Keys.

1. Create an API Key by going into the Stay Ai merchant portal, and navigating to Settings -> API Keys..

alt text

2. Click the "Add New API Key" button to open the Creation Dialog Box..

alt text

3. Enter a Name, Description, Email, and Scopes for the new API key you are generating. Click "OK" and we have created a new API Key!

alt text

4. Use the provided API key for generating requests by attaching them to the X-RETEXTION-ACCESS-TOKEN header.

Webhooks

Create Webhook Subscription

Now to the bread and butter of Stay Ai Open APIs. Here is how you create a new webhook subscription:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "event": "SUBSCRIPTION",
  "url": "https://your-site.com/hooks/retextion-subscription"
}

Response Body:

{
  "id": "cl88fxoi100409ha3qjo6n8iu",
  "createdAt": "2022-09-19T07:23:19.753Z",
  "updatedAt": "2022-09-19T07:23:19.753Z",
  "accountId": "ckw2lwyeu0002quosj3dbjcrm",
  "appId": "cl7t95c540173mia3u9ai5k09",
  "event": "SUBSCRIPTION",
  "url": "https://your-site.com/hooks/retextion-subscription"
}

HTTP Request

POST https://api.retextion.com/api/v2/webhooks

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
accountId	✖	STRING	Stay Ai Account ID (Required only when app is a global one)
event	✔️	STRING	Webhook Event ['SUBSCRIPTION', 'CANCELLATION', 'FAILED_PAYMENT', 'SUCCESSFUL_PAYMENT', 'PAUSED_SUBSCRIPTION', 'RESCHEDULED_SUBSCRIPTION', 'UPDATED_PAYMENT_METHOD', 'SUBSCRIPTION_UPDATE']
url	✔️	STRING	Webhook URL

Delete Webhook Subscription

We told you we will always support you! You can always delete a webhook subscription if needed. Here's how you can delete an existing webhook subscription by ID:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

true

HTTP Request

DELETE https://api.retextion.com/api/v2/webhooks/:webhookId

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Subscriptions

List All Subscriptions

This function is key for creating reporting based off of subscription data. Use this to list all subscriptions data for a specific store:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Query Params:

{
  "email": "customer@gmail.com",
  "createdAtMin": "1622259147715",
  "createdAtMax": "1662259147716",
  "updatedAtMin": "1622259147715",
  "updatedAtMax": "1662259147716",
  "nextBillingDateMin": "1622259147715",
  "nextBillingDateMax": "1662259147716",
  "page": "1",
  "pageSize": "10"
}

Response Body:

{
  "total": 6,
  "data": [
    {
      "id": "ckxf06git0141yhosiq7xpn0d",
      "subscriptionId": "gid://shopify/SubscriptionContract/1422098569",
      "customerId": "5311780257929",
      "emailAddress": "customer@gmail.com",
      "createdAt": "2021-12-20T18:19:52.997Z",
      "updatedAt": "2022-09-09T13:26:01.261Z",
      "nextBillingDate": "2022-09-12T00:00:00.000Z",
      "pausedUntil": "2022-09-12T00:00:00.000Z",
      "churnedAt": "2022-09-09T02:10:00.661Z",
      "cancelledAt": "2022-09-09T13:26:01.268Z",
      "cancellationReason": null,
      "price": 30,
      "deliveryPrice": 0,
      "currency": "USD",
      "status": "CANCELLED",
      "orderIntervalFrequency": 4,
      "orderIntervalUnit": "WEEK",
      "lineItems": [
        {
          "lineId": "gid://shopify/SubscriptionLine/9a246095-c0f9-46df-b37d-83aa16f94aad",
          "shopifyProductId": "gid://shopify/Product/6714938130569",
          "shopifyVariantId": "gid://shopify/ProductVariant/39732851179657",
          "quantity": 1,
          "unitPrice": 20,
          "subtotalPrice": 20
        },
        {
          "lineId": "gid://shopify/SubscriptionLine/aac0ce11-fd79-41f7-9463-a5d027c225c2",
          "shopifyProductId": "gid://shopify/Product/6714938130569",
          "shopifyVariantId": "gid://shopify/ProductVariant/39732851179657",
          "quantity": 1,
          "unitPrice": 10,
          "subtotalPrice": 10
        }
      ]
    },
    ...
  ]
}

HTTP Request

GET https://api.retextion.com/api/v2/subscriptions

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Query Params

Field	Required	Type	Description
accountId	✖	STRING	Stay Ai Account ID (Required only when app is a global one)
email	✖	STRING	Customer Email
createdAtMin	✖	INTEGER	Created Date Min Timestamp
createdAtMax	✖	INTEGER	Created Date Max Timestamp
updatedAtMin	✖	INTEGER	Updated Date Min Timestamp
updatedAtMax	✖	INTEGER	Updated Date Max Timestamp
nextBillingDateMin	✖	INTEGER	Next Billing Date Min Timestamp
nextBillingDateMax	✖	INTEGER	Next Billing Date Max Timestamp
page	✖	INTEGER	Page Number (Starting from 1)
pageSize	✖	INTEGER	Page Size (5 - 100)

Get Subscription by ID

Need to look into an issue, or pull data for a specific customer? Use the below to get a single subscription by ID:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "id": "gid://shopify/SubscriptionContract/3088646395",
  "createdAt": "2021-11-16T16:15:13Z",
  "status": {
    "status": "PAUSED",
    "pausedUntil": "2022-09-22T00:00:00.000Z"
  },
  "currencyCode": "USD",
  "lineCount": 1,
  "nextBillingDate": "2022-09-27T16:00:00.000Z",
  "discounts": {
    "edges": [
      {
        "node": {
          "value": {
            "percentage": 100
          },
          "id": "gid://shopify/SubscriptionManualDiscount/90fd0695-d3fc-46a6-8eee-6b767d2cfb7c",
          "type": "CODE_DISCOUNT",
          "title": "MYREDEEMCODE",
          "targetType": "LINE_ITEM"
        }
      }
    ]
  },
  "deliveryPrice": {
    "amount": "4.9",
    "currencyCode": "USD"
  },
  "customer": {
    "id": "gid://shopify/Customer/5819682554107",
    "firstName": "Test",
    "lastName": "Customer",
    "email": "testcustomer@gmail.com"
  },
  "billingPolicy": {
    "interval": "WEEK",
    "intervalCount": 1,
    "anchors": []
  },
  "deliveryMethod": {
    "address": {
      "address1": "860 Solimar Way 1",
      "address2": "",
      "city": "Mary Esther",
      "company": null,
      "country": "United States",
      "countryCode": "US",
      "firstName": "Test",
      "lastName": "Customer",
      "phone": "(555) 555-5555",
      "province": "Florida",
      "provinceCode": "FL",
      "zip": "55555"
    }
  },
  "lines": [
    {
      "id": "gid://shopify/SubscriptionLine/5de77699-db23-453c-b5e7-34dff32a8cf3",
      "title": "Test Product",
      "quantity": 1,
      "customAttributes": [],
      "currentPrice": {
        "amount": "1.0",
        "currencyCode": "USD"
      },
      "lineDiscountedPrice": {
        "amount": "0.0",
        "currencyCode": "USD"
      },
      "productId": "gid://shopify/Product/7333018239227",
      "sellingPlanId": "gid://shopify/SellingPlan/2415165691",
      "variantId": "gid://shopify/ProductVariant/41675008704763",
      "variantTitle": "Default",
      "variantImage": {
        "altText": null,
        "originalSrc": "https://cdn.shopify.com/s/files/1/0604/7111/6027/products/OIP.jpg?v=1639967903"
      },
      "isOneTime": false
    }
  ],
  "assignedPricingPolicy": null,
  "scheduledBillingDate": "2022-09-27T16:00:00.000Z",
  "shopifyOrders": [
    {
      "createdAt": "2022-08-30T15:02:35.675Z",
      "shopifyOrderId": "gid://shopify/Order/4860061581563"
    },
    ...
  ],
  "sellingPlanGroupData": {
    "id": "ckym2ip431698q6oslyyuhti3",
    "createdAt": "2022-01-19T21:39:28.803Z",
    "updatedAt": "2022-03-07T16:23:13.738Z",
    "customLabel": "Test SPG",
    "customDescription": "Test SPG",
    "shopifySellingPlanGroupId": "gid://shopify/SellingPlanGroup/686620923",
    "bundleMinimum": 0,
    "bundleMaximum": 0,
    "accountId": "ckw2ahw5s0002opos991i1num",
    "groupType": "STANDARD",
    "anchors": [],
    "sellingPlans": [
      {
        "id": "ckym2ip431699q6os7efxt7b0",
        "createdAt": "2022-01-19T21:39:28.803Z",
        "updatedAt": "2022-03-07T16:23:14.059Z",
        "shopifySellingPlanId": "gid://shopify/SellingPlan/2415165691",
        "billingPolicy": {
          "interval": "WEEK",
          "intervalCount": 1
        },
        "deliveryPolicy": {
          "interval": "WEEK",
          "intervalCount": 1
        },
        "pricingPolicies": [
          {
            "adjustmentType": "FIXED_AMOUNT",
            "adjustmentValue": {
              "amount": "0.0",
              "currencyCode": "USD"
            }
          }
        ],
        "options": "Weekly",
        "sellingPlanGroupId": "ckym2ip431698q6oslyyuhti3"
      }
    ]
  }
}

HTTP Request

GET https://api.retextion.com/api/v2/subscriptions/:subscriptionId

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Generate Portal Link

We know you aren't nosy, but sometimes you just need to see what's going on for a specific customer. Over at Stay Ai, we use this function to troubleshoot or validate a customer experience. Now you can do the same! Use the below to generate a customer portal link for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

Field	Required	Type	Description
email	✖	STRING	Customer email address
phone	✖	STRING	Customer phone number

Notes: At least one of above values should be provided.

{
  "email": "test@gmail.com",
  "phone" "1111111111"
}

Response Body:

{
  "link": "https://mystore.myshopify.com/apps/retextion?token=1a265c7f-5d4a-4b80-bfe3-3b95e9fe1102#/"
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/generate-portal-link

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Pause Subscription

Sometimes customers want to keep their subscription, but maybe need a little break. We support a "Pause" functionality, that allows customers to take that break if needed, without stopping their subscription. Here's how you can pause a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "pausedUntil": "2022-10-01",
  "initiator": "MERCHANT"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/pause

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
pauseUntil	✔️	DATE	Pause Util Date (YYYY-MM-DD format)
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Unpause Subscription

Here is how you can unpause a paused subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "initiator": "MERCHANT"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/unpause

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Cancel Subscription

Cancellations...it happens. Not our favorite feature, but here is how you can cancel a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "cancellationReasons": ["too expensive"],
  "initiator": "MERCHANT"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/cancel

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
cancellationReasons	x	ARRAY	list of reasons for cancellation of the subscription
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Reactivate Subscription

Here is how you can reactivate a cancelled subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "initiator": "MERCHANT"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/reactivate

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Get Order Now

Don't you love when customer's are passionate about your product? Some customers can't wait, and want their subscription order now. To cater to that, you can use the Get Order Now function for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/get-order-now

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Skip Next Order

Different than a pause, this keeps the existing cadence of the customer's subscription, but just skips the next order. This is a way for the customer to say "we will be back next shipment!". Follow the below guidelines to skip next order for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/skip-next-order

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Change Frequency

Adaptability is key when dealing with customers. That's why you can use Stay Ai Open APIs to update the billing and delivery frequencies for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
    "interval": 2,
    "intervalUnit" : "month",
    "initiator": "CUSTOMER"
}

Response Body:

{
    "id": "ckyexm4lq00687nn8gs9xxxxx",
    "createdAt": "2022-01-14T21:47:47.534Z",
    "updatedAt": "2023-03-08T17:17:54.629Z",
    "shopifySubscriptionContractId": "gid://shopify/SubscriptionContract/1487995000",
    "status": "ACTIVE",
    "shopifyCreatedAt": null,
    "nextBillingDate": "2023-05-08T17:17:50.000Z",
    "scheduledBillingDate": "2023-05-08T17:17:50.000Z",
    "pausedUntil": "2023-05-01T00:00:00.000Z",
    "dunningStartedAt": null,
    "dunningExitedAt": null,
    "cancelledAt": null,
    "cancellationReasons": null,
    "billingPolicy": {
        "interval": "MONTH",
        "intervalCount": 2
    },
    "anchors": null,
    "assignedPricingPolicy": null,
    "address": null,
    "giftAddress": null,
    "lineCount": 1,
    "originOrderId": null,
    "originOrderPrice": 40.9,
    "currencyCode": "USD",
    "failedPaymentBillingAttempts": 0,
    "outOfStockBillingAttempts": 0,
    "prePaid": false,
    "prepaidNextDeliveryDate": null,
    "prepaidShipmentsRemaining": 0,
    "prepaidDeliveryPolicy": null,
    "prepaidAllowRenewal": false,
    "prepaidtotalShipmentsPerCycle": null,
    "paymentMethodId": null,
    "deliveryPrice": 0,
    "deletedAt": null,
    "lastSeenIp": null,
    "churnRisk": null,
    "accountId": "ckw2ildx000027us385f1xxx",
    "accountCustomerId": "ckyexm39200497nn8eq3xxxx"
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/change-frequency

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
orderInterval	✔️	NUMBER	Value of order period
billingInterval	✔️	NUMBER	Value of billing period
intervalUnit	✔️	String	Duration type applied to request intervals. Can be: `day`, `week`, `month`, `year`
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Set Next Billing Date

Change or update when the customer will get charged for the subscription. Here is how you can set the next billing date for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "nextBillingDate": "2022-10-01"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/set-next-billing-date

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
nextBillingDate	✔️	DATE	Next Billing Date (YYYY-MM-DD format)

Set Shipping Address

Change or update where the ordered products will be delivered for the subscription. Here is how you can set the shipping address for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
    "firstName": "Test",
    "lastName": "User",
    "address1": "address1",
    "address2": "",
    "city": "city",
    "country": "US",
    "province": "Iowa",
    "provinceCode": "IA",
    "zip": "12345",
    "phone": "+1234567890"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/set-shipping-address

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
firstName	✔️	STRING	First Name
lastName	✔️	STRING	Last Name
address1	✔️	STRING	Address1
address2	✖	STRING	Address2
city	✔️	STRING	City
country	✔️	STRING	Country
province	✔️	STRING	Province
provinceCode	✔️	STRING	Province Code
zip	✔️	STRING	Zip Code
phone	✔️	STRING	Phone Number

Add Lines

Add lines to a subscription in an array:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{ 
  "lines": [{
    "variantId": "gid://shopify/ProductVariant/41675008704763",
    "price": 15,
    "quantity": 1,
    "isOneTime": true
  }]
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/add-lines

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
Lines	✔️	[OBJECT]	An array of lines with the values listed below
variantId	✔️	STRING	shopify product variant ID of the new line item to be added
price	✔️	INT	price of new product
quantity	✔️	INT	quantity of new product
isOneTime	✔️	BOOLEAN	A Boolean to determine if the line is a one-time product

Swap Product

Switch out one product for another:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
    "lineId": "gid://shopify/SubscriptionLine/7a250aed-2c48-4ab1-8518-b7440d6cxxx",
    "variantId": "gid://shopify/ProductVariant/39964047110000",
    "price": "5",
    "quantity": "1",
    "initiator": "CUSTOMER"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/swap-product

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
lineId	✔️	STRING	Shopify subscription line ID of the existing line item to be swapped out
variantId	✔️	STRING	shopify product variant ID of the new line item to be added
price	✔️	STRING	price of new product
quantity	✔️	STRING	quantity of new product
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Remove Lines

Remove lines from a subscription in an array:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{ 
  "lines": ["clgazalu3000009mg1a9cguco", "clgazb6hi000209mg3wi8algw"]
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/remove-lines

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
Lines	✔️	[STRING]	An array of Stay line item IDs

Add Discount

Deals! Who doesn't love them. That's why you can use Stay Ai Open APIs to apply a discount code for a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "redeemCode": "MYPROMOCODE",
  "initiator": "MERCHANT"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/add-discount

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
redeemCode	✔️	STRING	Redeem Code
initiator	x	STRING	Initiating actor. Can be `MERCHANT` or `CUSTOMER`. Default: `MERCHANT`

Remove Discount

In the case that you applied a discount where you didn't want to, we allow you remove it with no problem. Here's how you can remove a discount line from a specific subscription contract:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{
  "discountId": "gid://shopify/SubscriptionManualDiscount/90fd0695-d3fc-46a6-8eee-6b767d2cfb7c"
}

Response Body:

{
  "success": true
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/remove-discount

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
discountId	✔️	STRING	Shopify Discount Id (e.g. gid://shopify/SubscriptionManualDiscount/90fd0695-d3fc-46a6-8eee-6b767d2cfb7c)

Get Meta Data

Gets a list of all meta data fields for a subscription:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

[
    {
        "id": "clge5n9hq0010u8vvub3llzmj",
        "accountId": "clgdzzj680002d9vvmlsp9p7f",
        "createdAt": "2023-04-12T20:39:33.326Z",
        "updatedAt": "2023-04-12T20:39:33.326Z",
        "subscriptionContractId": "clge4b20x0281dbvv7rlcmtm1",
        "metaKey": "Key 1",
        "metaValue": "Value 1"
    },
    {
        "id": "clgf8j2ro00733uvve2dxauml",
        "accountId": "clgdzzj680002d9vvmlsp9p7f",
        "createdAt": "2023-04-13T14:48:03.012Z",
        "updatedAt": "2023-04-13T14:48:03.013Z",
        "subscriptionContractId": "clge4b20x0281dbvv7rlcmtm1",
         "metaKey": "Key 2",
        "metaValue": "Value 2"
    },
    {
        "id": "clge5nf7t0027u8vvlofyxdom",
        "accountId": "clgdzzj680002d9vvmlsp9p7f",
        "createdAt": "2023-04-12T20:39:40.745Z",
        "updatedAt": "2023-04-13T21:58:15.964Z",
        "subscriptionContractId": "clge4b20x0281dbvv7rlcmtm1",
         "metaKey": "Key 3",
        "metaValue": "Value 3"
    }
]

HTTP Request

GET https://api.retextion.com/api/v2/subscriptions/:subscriptionId/meta-data

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Add Meta Data

Upserts Meta-Data to a subscription:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Body:

{ 
  "key": "Key",
  "value": "Value"
}

Response Body:

{
    "id": "clge5nf7t0027u8vvlofyxdom",
    "accountId": "clgdzzj680002d9vvmlsp9p7f",
    "createdAt": "2023-04-12T20:39:40.745Z",
    "updatedAt": "2023-04-13T21:58:15.964Z",
    "subscriptionContractId": "clge4b20x0281dbvv7rlcmtm1",
    "metaKey": "Key",
    "metaValue": "Value"
}

HTTP Request

POST https://api.retextion.com/api/v2/subscriptions/:subscriptionId/meta-data

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Body

Field	Required	Type	Description
key	✔️	[STRING]	Meta Data Key
value	✔️	[STRING]	Meta Data Value

Delete Meta Data

Delete meta data entries:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "success": true
}

HTTP Request

DELETE https://api.retextion.com/api/v2/subscriptions/:subscriptionId/meta-data/:metaDataId

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Orders

List All Orders

This is for you data analysts out there! In the same way we allow you to pull all subscriptions for a specific store, you can also use the below to list orders data for a specific store:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Request Query Params:

{
  "createdAtMin": "1622259147715",
  "createdAtMax": "1662259147716",
  "updatedAtMin": "1622259147715",
  "updatedAtMax": "1662259147716",
  "page": "1",
  "pageSize": "10"
}

Response Body:

{
  "total": 1645,
  "data": [
    {
      "orderId": "gid://shopify/Order/4821466644731",
      "orderName": "#ret2123",
      "customerId": "6028328403195",
      "subscriptionId": "gid://shopify/SubscriptionContract/3432546555",
      "createdAt": "2022-07-23T17:02:04.223Z",
      "updatedAt": "2022-10-17T13:25:26.122Z",
      "fulfillmentStatus": "UNFULFILLED",
      "currency": "USD",
      "totalPrice": 13.9,
      "cartDiscountAmount": 0,
      "currentTotalTax": 0,
      "totalShippingPrice": 4.9,
      "address": {
        "zip": "59771",
        "city": "Bozeman",
        "phone": "6504950577",
        "company": null,
        "country": "United States",
        "address1": "PO Box 43",
        "address2": "",
        "lastName": "Ten",
        "province": "Montana",
        "firstName": "Kate",
        "countryCode": "US",
        "provinceCode": "MT"
      },
      "tags": "Active Subscription,Subscription",
      "lineItems": [
        {
          "lineId": "gid://shopify/LineItem/12293570625787",
          "productTitle": "Product with Variants Test 1",
          "shopifyProductId": "gid://shopify/Product/7589221728507",
          "variantTitle": "Blue / Small",
          "shopifyVariantId": "gid://shopify/ProductVariant/42660789453051",
          "sku": null,
          "quantity": 1,
          "subtotalPrice": 9
        }
      ]
    },
    ...
  ]
}

HTTP Request

GET https://api.retextion.com/api/v2/orders

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Request Query Params

Field	Required	Type	Description
accountId	✖	STRING	Stay Ai Account ID (Required only when app is a global one)
createdAtMin	✖	INTEGER	Created Date Min Timestamp
createdAtMax	✖	INTEGER	Created Date Max Timestamp
updatedAtMin	✖	INTEGER	Updated Date Min Timestamp
updatedAtMax	✖	INTEGER	Updated Date Max Timestamp
page	✖	INTEGER	Page Number (Starting from 1)
pageSize	✖	INTEGER	Page Size (5 - 100)

Get Order by ID

Need to look into an issue, or pull data for a specific customer? Use the below to get a single order by ID or Shopify order ID:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "orderId": "gid://shopify/Order/4821466644731",
  "orderName": "#ret2123",
  "customerId": "6028328403195",
  "subscriptionId": "gid://shopify/SubscriptionContract/3432546555",
  "createdAt": "2022-07-23T17:02:04.223Z",
  "updatedAt": "2022-10-17T13:25:26.122Z",
  "fulfillmentStatus": "UNFULFILLED",
  "currency": "USD",
  "totalPrice": 13.9,
  "cartDiscountAmount": 0,
  "currentTotalTax": 0,
  "totalShippingPrice": 4.9,
  "address": {
    "zip": "59771",
    "city": "Bozeman",
    "phone": "6504950577",
    "company": null,
    "country": "United States",
    "address1": "PO Box 43",
    "address2": "",
    "lastName": "Ten",
    "province": "Montana",
    "firstName": "Kate",
    "countryCode": "US",
    "provinceCode": "MT"
  },
  "tags": "Active Subscription,Subscription",
  "lineItems": [
    {
      "lineId": "gid://shopify/LineItem/12293570625787",
      "productTitle": "Product with Variants Test 1",
      "shopifyProductId": "gid://shopify/Product/7589221728507",
      "variantTitle": "Blue / Small",
      "shopifyVariantId": "gid://shopify/ProductVariant/42660789453051",
      "sku": null,
      "quantity": 1,
      "subtotalPrice": 9
    }
  ]
}

HTTP Request

GET https://api.retextion.com/api/v2/orders/:orderId

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Selling Plan Groups

Get Selling Plan Group by ID

Use the endpoint below to get a single selling plan group by Id.

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

{
  "id": "ckxgbrfgo0114b1os3c80g52s",
  "createdAt": "2021-12-21 16:31:53.352",
  "updatedAt": "2021-12-21 17:41:24.291",
  "customLabel": "Test4",
  "customDescription": "Test4",
  "shopifySellingPlanGroupId": "gid://shopify/SellingPlanGroup/409338043",
  "accountId": "ckwzr74ci00366tosk1vx1io6",
  "anchors": null,
  "groupType": "STANDARD",
  "bundleMaximum": 0,
  "bundleMinimum": 0
},

HTTP Request

GET https://api.retextion.com/api/v2/selling-plan-groups/:sellingPlanGroupId

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Products

Get swap products

Looking to change up things on a subscription, list all products that are legible for swapping out with an item in said subscription:

Request Header:

{
  "X-RETEXTION-ACCESS-TOKEN": "{{APP_API_KEY}}"
}

Response Body:

[
    {
        "id": "gid://shopify/ProductVariant/39964047147000",
        "price": "5.00",
        "displayName": "Product with variants - vanila taste",
        "image": {
            "originalSrc": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/photo-1560008581-09826d1de69e.jpg?v=1644360477",
            "small": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/photo-1560008581-09826d1de69e_360x.jpg?v=1644360477",
            "large": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/photo-1560008581-09826d1de69e_720x.jpg?v=1644360477"
        }
    },
    {
        "id": "gid://shopify/ProductVariant/40936564326000",
        "price": "20.00",
        "displayName": "Avocado Salad - Purple Salad",
        "image": {
            "originalSrc": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/salad.jpg?v=1645041173",
            "small": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/salad_360x.jpg?v=1645041173",
            "large": "https://cdn.shopify.com/s/files/1/0552/9819/5593/products/salad_720x.jpg?v=1645041173"
        }
    }
]

HTTP Request

GET https://api.retextion.com/api/v2/products/:shopifySubscriptionLineId/swap-product

Request Header

Field	Required	Type	Description
X-RETEXTION-ACCESS-TOKEN	✔️	STRING	App API Key

Questions?

We hope this was helpful, but we are here for you! And of course, we at Stay Ai are always looking for feedback on how to support our clients and customers to the best of our ability. So if you have any questions, or feedback, please shoot us an email at engineering@retextion.com. We're looking forward to it!