Seal Subscriptions Merchant API Documentation


What is the Seal Subscriptions Merchant API?

The Seal Subscriptions Merchant API is a public REST API for Seal Subscriptions app, which allows merchants to retrieve details about their subscriptions, subscription rules and create webhooks to get notified whenever a specific object changes in the app.
The full documenation of what you can do with the API is listed on this page.

Feel free to use our API client, which was created to save you some valuable time. You can fork it from our Github page: https://github.com/SealSubscriptions/Seal-Subscriptions-php-API-client

Authentication

The API client authenticates itself with the API token which can be found for each shop in the Seal Subscriptions app > Settings > General Settings > API. The token has to be sent as a value for the X-Seal-Token header. Token is unique for each shop and should be protected the same way you protect your usernames and passwords.

Retrieve subscriptions

The subscription retrieval can be done with a simple GET call to a /subscriptions endpoint.
Here is an example of such call:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

You can also search for subscriptions by customer's email, first name or last name with the query GET parameter.
Here is an example on how to find subscriptions that contain a name John:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions?query=john \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

Subscriptions are always paginated (50 subscriptions per page) and you can define which page you want with the page GET parameter.
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscriptions?page=2 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

Here is a list of available get parameters with description of available values you can use:
  • query: value can be any search string. Default value is an empty string.
  • page: value can be any number and represents the requested page. Default value is 1.
  • paused-only: value can be "true" or "false". Default value is "false."
  • cancelled-only: value can be "true" or "false". Default value is "false."


Get more info about a specific subscription

You can retrieve a specific subscription and all info related to it with a GET call to a /subscription endpoint.
Here is an example of such call:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription?id=12345 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Retrieve subscription rules

You can also get list of subscription ruls with a GET call to a /subscription-rules endpoint.
Here is an example of such call:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-rules?page=1 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Cancel or pause a specific subscription

To cancel or pause a specific subscription, send a PUT request to /subscription endpoint.

Cancelling a subscription:
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"action": "cancel"
	  }'

Pausing a subscription:
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"action": "pause"
	  }'


Reactivate or resume a specific subscription

To reactivate or resume a specific subscription, send a PUT request to /subscription endpoint. There is almost no difference in the resume and reactivate actions, except that you generally resume paused subscriptions and reactivate the cancelled subscriptions. But you can use any of these two actions when you want to reactivate or resume a subscription, as the effect will be the same.

Reactivate a subscription:
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"action": "reactivate"
	  }'

Resume a subscription:
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"action": "resume"
	  }'


Retrieve specific subscription rule

You can retrieve a specific subscription rule with a GET call to a /subscription-rule endpoint, where you add the ID of the rule as a GET parameter.
Here is an example of such call:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-rule?id=12345 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'


Edit subscription rule

To edit a specific subscription rule, send a PUT request to /subscription-rule endpoint.
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-rule \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{"id": 1234,"product_variants": [{"product_id": "4315124891700","variant_id": null}, {"product_id":4315121156148, "variant_id": 39418377830452}]}'

Currently, you can edit the following parts of the subscription rule
  • name, which represents a name of the subscription rule
  • options, which represent the label for the plan selector such as Deliver every
  • product_variants, which represents the product variants linked to the auto-charging subscription rule.
The product_variants parameter has to be an array of products, where each element contains product_id and variant_id field. For example:
{
		id: 123123, 				// An ID of the subscription rule
		name: "Subscribe & save",	// Name of the subscription rule
		options: "Delive every",	// Label for the plan selector in auto-charging widgets
		product_variants: [			// List of product variants included in auto-charging subscription rule
			{
				product_id: 1231241,
				variant_id: 122423	// We are adding a specific variant to the subscription rule
			},
			{
				product_id: 1231242,
				variant_id: null 	// We are adding all variants from this product to the subscription rule
			}
		]

To remove a variant/product from the rule, just remove it from the product_variants array. To add it to the rule, just add it to the product_variants array. Mind that the array of products and variants you send to the API will overwrite the existing product variants linked to the subscription rule. It won't just add them to the rule.


Create a webhook

To create a webhook which will be executed whenever a subscription is created, send a POST request to /webhooks endpoint.
curl -X POST \
	  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"topic": "subscription/created", 
		"address": "YOUR_HTTPS_WEBHOOK_ADDRESS"
	  }'

When the specified action happens (e.g. subscription is created), our system will send a request with the subscription details to the webhook address you specified in your webhook configuration. Our system will try to deliver the webhook for up to 20 times until your server responds with a HTTP code of 200 OK within 5 seconds. If the webhook can't be delivered after 20 tries, then the whole webhook configuration will be removed.

The payload of each webhook request (and other API responses) will be signed with a HMAC code which will be sent as the value of the X-Seal-Hmac-Sha256 header. The HMAC code will be computed with the JSON encoded webhook payload and the Seal API secret. You can get the Seal API secret of the shop you are making requests for in Seal Subscriptions app > Settings > General Settings > API. It is highly recommended to verify the HMAC signature and reject the content if the signatures don't match. HMAC signature allows you to verify the integrity and authenticity of the message.
You can see how you can verify the signature in our PHP Library available on Github.
https://github.com/SealSubscriptions/Seal-Subscriptions-php-API-client

The currently available webhook topics are:
  • subscription/created
  • subscription/updated
  • subscription_rule/created
  • subscription_rule/updated

This is how you can get your current webhooks:
curl -X GET \
	  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

And this is how you delete a specific webhook:
curl -X DELETE \
	  https://app.sealsubscriptions.com/shopify/merchant/api/webhooks?id=12345 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

This is a sample payload of the subscription_rule/created webhook:
{
		"id": 123124,
		"name": "Monthly subscription",
		"option": "Deliver every",
		"payment_type": "auto-charge",
		"product_variants": [{
				"product_id": "431512499999999",
				"variant_id": null
			}, {
				"product_id": "43151299999999",
				"variant_id": null
			}
		],
		"selling_plans": [{
				"name": "Monthly subscription",
				"option": "month",
				"delivery_interval": "month",
				"delivery_interval_count": 1,
				"billing_interval": "month",
				"billing_interval_count": 1,
				"pricing_policy_fixed_adjustment_type": "",
				"pricing_policy_fixed_adjustment_value": "",
				"pricing_policy_recurring_adjustment_type": "",
				"pricing_policy_recurring_adjustment_value": "",
				"pricing_policy_recurring_after_cycle": 1,
				"pricing_policy_recurring_active": 0,
				"selling_plan_id": "123123123",
				"billing_min_cycles": 0, /* 0 represents an unset value*/
				"billing_max_cycles": 0, /* 0 represents an unset value*/
				"description": "Subscribe"
			}
		]
	}
	

This is a sample payload of the subscription/updated webhook:
{
		"id": 123123,
		"order_placed": "2021-05-25T05:17:59-04:00",
		"internal_id": 1038,
		"delivery_interval": "2 week",
		"billing_interval": "2 week",
		"order_id": "12312312313",
		"email": "test@sealsubscriptions.com",
		"currency": "USD",
		"first_name": "John",
		"last_name": "Doe",
		"s_first_name": "John",
		"s_last_name": "Doe",
		"s_address1": "Seal Subscriptions street 5",
		"s_address2": "",
		"s_phone": "132313",
		"s_city": "New York",
		"s_zip": "10001",
		"s_province": "New York",
		"s_country": "United States",
		"s_company": "",
		"s_country_code": "US",
		"s_province_code": "NY",
		"b_first_name": "",
		"b_last_name": "",
		"b_address1": "",
		"b_address2": "",
		"b_phone": "",
		"b_city": "",
		"b_zip": "",
		"b_province": "",
		"b_country": "",
		"b_company": "",
		"b_country_code": "",
		"b_province_code": "",
		"total_value": 1776,
		"admin_note": "",
		"subscription_type": 2,
		"status": "ACTIVE",
		"customer_id": "15512324",
		"billing_min_cycles": 3,
		"billing_max_cycles": 15,
		"note": "",
		"note_attributes": [],
		"edit_url": "", /* Redacted in documentation, as this URL has to be kept safe */
		"items": [{
				"id": 1234,
				"product_id": "",
				"variant_id": "",
				"title": "Two teddy bears",
				"variant_sku": "2BEARS-MEDIUM",
				"quantity": 1,
				"price": "1776.0",
				"total_discount": "0",
				"discount_per_item": "",
				"taxable": 1,
				"requires_shipping": 1,
				"original_price": "1776.0",
				"original_amount": 1776,
				"discount_value": 0,
				"discount_amount": 0,
				"final_price": "1776.0",
				"final_amount": 1776,
				"properties": [],
				"cycle_discounts": []
			}
		],
		/* Billing attempts were modified before adding them to the API documentation, so the dates in this sample are not correct according to the desired delivery schedule */
		"billing_attempts": [{
				"id": 2343421,
				"date": "2021-10-12T09:00:00+00:00",
				"status": "completed",
				"order_id": "564564121223",
				"error_code": "",
				"error_message": "",
				"triggered_manually": ""
			}, {
				"id": 234234,
				"date": "2021-11-26T09:00:00+00:00",
				"status": "",
				"order_id": "",
				"error_code": "",
				"error_message": "",
				"triggered_manually": ""
			}
		],
		"invoices": [],
		"fulfillment_orders": [],
		"tags": [],
		"log": []
	}

	


Reschedule or delete a billing attempt

To reschedule a specific billing attempt, send a PUT request to /subscription-billing-attempt endpoint. You can only reschedule billing attempts that weren't yet processed.
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-billing-attempt \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"subscription_id": 123123,
		"date": "2022-01-05",
		"time": "14:30",
		"timezone": "-04:00",
		"action": "reschedule"
	  }'

To reschedule a billing attempt, you have to add payload data to the PUT request, which contains:
  • ID of the billing attempt you want to reschedule in parameter "id"
  • ID of the subscription to which the billing attempt is bound in parameter "subscription_id"
  • desired date to which you want to reschedule the attempt in parameter "date"
  • desired time to which you want to reschedule the attempt in parameter "time"
  • timezone in which the supplied date and time were provided in parameter "timezone"
  • "reschedule" as a value of the "action" parameter to let the API know that you want to reschedule the attempt.

And this is how you can delete a specific billing attempt
curl -X DELETE \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-billing-attempt?id=12345\&subscription_id=12345 \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN'

To DELETE a billing attempt, you have to provide the billing attempt ID in the "id" GET parameter and the subscription ID to which the attempt is bound in the "subscription_id" GET parameter. You can only delete the billing attempts that weren't yet processed.

Note: The system will always try to keep billing attempts scheduled for the next 65 days, so even if you delete all biling attempts, they will get rescheduled again in a few hours. The usage of this endpoint is recommended if you want to move the next billing attempt to a specific day and then remove other billing attempts so that the system will schedule other billing attempts from your last billing attempt.


Reschedule a fulfillment order

To reschedule a specific fulfillment order (for prepaid subscriptions), send a PUT request to /subscription-fulfillment-order endpoint.
curl -X PUT \
	  https://app.sealsubscriptions.com/shopify/merchant/api/subscription-fulfillment-order \
	  -H 'Content-Type: application/json' \
	  -H 'X-Seal-Token: YOUR_SEAL_TOKEN' \
	  -d '{
		"id": 123123, 
		"subscription_id": 123123,
		"date": "2022-01-05",
		"time": "14:30",
		"timezone": "-04:00",
		"action": "reschedule"
	  }'

To reschedule a fulfillment order, you have to add payload data to the PUT request, which contains:
  • ID of the fulfillment order you want to reschedule in parameter "id"
  • ID of the subscription to which the fulfillment order is bound in parameter "subscription_id"
  • desired date to which you want to reschedule the fulfillment order in parameter "date"
  • desired time to which you want to reschedule the fulfillment order in parameter "time"
  • timezone in which the supplied date and time were provided in parameter "timezone"
  • "reschedule" as a value of the "action" parameter to let the API know that you want to reschedule the fulfillment order.