Subscription Management: Developer Interface

This page will walk you through use cases using the Arc XP Subscriptions Sales develop APIs.

Note

You can distinguish developer APIs because they contain an /api/ as part of the endpoint.

As part of some updates, Arc XP Identity streams relevant events via WebSocket, see How-to listen Web Socket events and Implement IFX email service provider for additional details.

You can also view Sales WebSocket events here.

Prerequisites

• Know the base_URL, where org is your organization id.
  • api.sandbox.{org}.arcpublishing.com (for sandbox environment)
  • api.{org}.arcpublishing.com (for production environment)
• You will need a token for either the production or sandbox environment, as appropriate: ARC_ACCESS_TOKEN (see Developer Token which can be configured in Developer Center ).
• Some developers APIs are site-specific and require you to pass the Arc-Site header.

Example

  curl --location --request GET 'https://{base_URL}/sales/api/v1/profile/{uuid}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ARC_ACCESS_TOKEN}' \
--header 'Arc-Site: {siteID}'

Subscription Management

You can manage some aspects of subscriptions using the develoepr APIs. You can view all subscription linked to a user or checkout details on a subscription with following APIs.

GET {base_URL}/sales/api/v1/subscription/all

GET {base_URL}/sales/api/v1/subscription/{id}/details

You can extend the subscription so that the next event date is extended to the requested data. This will require reason code if it’s enabled.

This will also fire EXTEND_SUBSCRIPTION event.

PUT {base_URL}/sales/api/v1/subscription/{id}/extend

You can also grant a free subscription with an expiration date using the following API. This will also fire START_SUBSCRIPTION and GRANT_FREE_SUBSCRIPTION events.

POST {base_URL}/sales/api/v1/subscription/free

Manage Price Changes

You can schedules a price change for a subscription with a specific subscription ID. The new price rate needs to be added prior to starting the price change and applying it to the subscription. The price change will go into affect on the first renewal after the effectiveDate that is entered as part of the API.

Three WebSocket Events are sent at different intervals when a price change is scheduled; PRICE_CHANGE_SCHEDULED_EVENT, UPCOMING_PRICE_CHANGE_EVENT (sent 14 days prior to price change), UPDATE_SKU_PRICECODE.

Few things to consider:

• Changing price only applies to “paid” subscriptions. “cancelled”, “terminated”, “free” and “linked” subscriptions cannot have a price change. Only an active or suspended subscription can have its price changed.
• SKUs and priceCodes must exist in ARC and in the published status. See Product statuses for more details. The new price rate needs to be added in the Arc Subscriptions Admin prior to starting the price change and applying it the subscription.
• Product SKU and priceCodes (old and new) need to be associated.
• The new price should be equal to or higher than zero. Note: Paypal doesn’t accept zero-dollar price change renewals.
• When several changes are made over the same price, these changes are queued and will be applied in order.

PUT {base_URL}/sales/api/v1/subscription/{id}/pricechange

Schedules a price or product change based on the current product SKU, Price Code and the date these were started. The new price rate needs to be added prior to starting the price change and applying it the subscription. The price change will go into affect on the first renewal after the effectiveDate that is entered as part of the API. These provide clients a method for updating all customers who have been subscribers of a specific product for a length of time.

Same three WebSocket events are fired as the above API.

Also same considerations apply to this batch API as the above API. One additional consideration for the batch api is that if a change price is scheduled for a batch of users, this will only affect those subscriptions that exist when the price change is requested.

POST {base_URL}/sales/api/v1/batchpricechange

Linked Subscription

Linked subscription lets clients connect external subscriptions with Arc Subscriptions.

The following API creates a new subscription by linking it to an external system. Also, this will fire START_SUBSCRIPTION WebSocket event after every successful linked subscription.

POST {base_URL}/sales/api/v1/subscription/link

Example of the request body:

  {
    "sku": "1A123",
    "priceCode": "1A123",
    "token": "1A123",
    "expirationDateUTC": "2022-02-22 11:11:00",
    "clientId": "string"
  }

The follow API revokes all subscriptions that were previously linked with the token specified in the request body. In the body the SKU and priceCode parameters should both have the value “REVOKE”. WebSocket Event: The TERMINATE_SUBSCRIPTION event is sent after every successful revoke subscription.

PUT {base_URL}/sales/api/v1/subscription/link/revoke

  {
    "sku": "REVOKE",
    "priceCode": "REVOKE",
    "token": "1A123"
  }

Migrate subscriptions

Arc XP Sales migration API allows you to seamlessly transfer your active subscriptions and their transactions into Arc XP Subscriptions with no impact to your users. See Use Sales developer APIs to migrate subscriptions into Arc XP Subscriptions for additional details. Calling the following API will fire SUBSCRIPTION_MIGRATION and/or SUBSCRIPTION_PAYMENT_MIGRATION event.

POST {base_URL}/sales/api/v1/migrate

Group package based on domain

Group subscription APIs can be used to provide readers with access through a group access code associated with their email domain. This enables them to log into their accounts and access content from any device and location.

You will need to create an email domain whitelist entry first using the following api. CREATE_EMAIL_DOMAIN event will be triggered.

POST {base_URL}/sales/api/v1/emailgroupsub

The above API will take in a few fields including, emailDomain, ownerClientId, and productSKU and return accessCode among other fields. The accessCode with the clientId needs to be passed to the next API to add group subscription member. You can also manage group subscriptions through Admin App. See Group package based on domain for details.

POST {base_URL}/sales/api/v1/emailgroupsub/join

You can remove one or more group subscription members using the following API. This API will take in array of subscriptionIDs and the subscriptions will be queued for termination which will happen the next time the termination engine runs.

DELETE {base_URL}/sales/api/v1/emailgroupsub/{id}/members

Enterprise Subscription

Enterprise subscriptions offer advanced features such as issuing unique nonces for secure user access, updating group details, and extracting detailed subscription data for auditing. Subscriptions can be terminated individually via APIs or through the CSR interface. Additional functionality includes creating and deleting enterprise groups and retrieving information on active groups. With these APIs, organizations can efficiently manage complex subscription models, ensuring a streamlined experience for both administrators and users.

Manage Enterprise Group

Create a new Enterprise group

POST {base_URL}/sales/api/v2/subscriptions/enterprise

Update Enterprise group

While this API can update both the name and SKU of an Enterprise group, subscriptions created from the Enterprise group will not be updated with the new values.

PUT {base_URL}/sales/api/v2/subscriptions/enterprise/{id}

Delete an Enterprise group

Any subscriptions associated with the group will be scheduled to be terminated with the terminations taking place in batches starting up to one hour later.

DELETE {base_URL}/sales/api/v2/subscriptions/enterprise/g/{id}

Manage Enterprise Group Subscription

Create a nonce for an enterprise subscription

This developer API issues nonces that can be redeemed for subscriptions. Each nonce will be valid for 14 days. See Enterprise subscription for details.

GET {base_URL}/sales/api/v2/subscriptions/enterprise/{id}

Terminate an enterprise subscription

Terminate an individual enterprise subscription owned by a reader

DELETE {base_URL}/sales/api/v2/subscriptions/enterprise/{id}

Get a list of all Enterprise groups

GET {base_URL}/sales/api/v2/subscriptions/enterprise

Order Management

You can interact with a customer’s order using order APIs. You can search orders and get details on a certain order using following APIs:

GET {base_URL}/sales/api/v1/order/detail/{orderNumber}

GET {base_URL}/sales/api/v1/order/search

Reason code

The following API can be used to retrieve all reason codes configured on the tenant’s account.

GET {base_URL}/sales/api/v1/ccreasoncode/all