# Subscription Management: Developer Interface

Source: https://dev.arcxp.com/subscriptions/sales/learn/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](https://dev.arcxp.com/subscriptions/identity/build/ifx-email-servic-provider-integration-and-websocket-events/) for additional details.
> 
> You can also view Sales WebSocket events [here](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/).

## 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](https://docs.arcxp.com/alc/en/how-to-create-a-restricted-access-developer-token?sys%5Fkb%5Fid=5579a28747c87990eee38788436d43e1&id=kb%5Farticle%5Fview&sysparm%5Frank=1&sysparm%5FtsqueryId=5ecb54b0934296104792b0cdfaba103e) ).
- Some developers APIs are site-specific and require you to pass the `Arc-Site` header.

**Example**

Terminal window

```bash
  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](https://dev.arcxp.com/api/subscriptions-apis)

[GET {base\_URL}/sales/api/v1/subscription/{id}/details](https://dev.arcxp.com/api/subscriptions-apis)

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](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#extend-subscription-payment) event.

[PUT {base\_URL}/sales/api/v1/subscription/{id}/extend](https://dev.arcxp.com/api/subscriptions-apis)

You can also grant a free subscription with an expiration date using the following API. This will also fire [START\_SUBSCRIPTION](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#start-subscription) and [GRANT\_FREE\_SUBSCRIPTION](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#grant-free-subscription) events.

[POST {base\_URL}/sales/api/v1/subscription/free](https://dev.arcxp.com/api/subscriptions-apis)

### 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](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#price-change-scheduled), [UPCOMING\_PRICE\_CHANGE\_EVENT](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#upcoming-price-change) (sent 14 days prior to price change), [UPDATE\_SKU\_PRICECODE](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#update-product-andor-price).

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](https://dev.arcxp.com/subscriptions/sales/configure/set-up-products-and-prices/#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](https://dev.arcxp.com/api/subscriptions-apis)

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](https://dev.arcxp.com/api/subscriptions-apis)

### Linked Subscription

[Linked subscription](https://dev.arcxp.com/subscriptions/sales/learn/what-is-a-subscription/#linked) 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](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#start-subscription) WebSocket event after every successful linked subscription.

[POST {base\_URL}/sales/api/v1/subscription/link](https://dev.arcxp.com/api/subscriptions-apis)

Example of the request body:

```json
  {
    "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](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#terminate-subscription) event is sent after every successful revoke subscription.

[PUT {base\_URL}/sales/api/v1/subscription/link/revoke](https://dev.arcxp.com/api/subscriptions-apis)

```json
  {
    "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](https://dev.arcxp.com/subscriptions/sales/learn/use-sales-developer-apis-to-migrate-subscription-into-arc-xp) for additional details. Calling the following API will fire [SUBSCRIPTION\_MIGRATION](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#subscription-migration) and/or [SUBSCRIPTION\_PAYMENT\_MIGRATION](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#subscription-payment-migration) event.

[POST {base\_URL}/sales/api/v1/migrate](https://dev.arcxp.com/api/subscriptions-apis)

### 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](https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/#create-email-domain) event will be triggered.

[POST {base\_URL}/sales/api/v1/emailgroupsub](https://dev.arcxp.com/api/subscriptions-apis)

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](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#group-package-based-on-domain) for details.

[POST {base\_URL}/sales/api/v1/emailgroupsub/join](https://dev.arcxp.com/api/subscriptions-apis)

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](https://dev.arcxp.com/api/subscriptions-apis)

### 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](https://dev.arcxp.com/api/subscriptions-apis)

**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}](https://dev.arcxp.com/api/subscriptions-apis)

**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}](https://dev.arcxp.com/api/subscriptions-apis)

#### 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](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#enterprise-subscription) for details.

[GET {base\_URL}/sales/api/v2/subscriptions/enterprise/{id}](https://dev.arcxp.com/api/subscriptions-apis)

**Terminate an enterprise subscription**

Terminate an individual enterprise subscription owned by a reader

[DELETE {base\_URL}/sales/api/v2/subscriptions/enterprise/{id}](https://dev.arcxp.com/api/subscriptions-apis)

**Get a list of all Enterprise groups**

[GET {base\_URL}/sales/api/v2/subscriptions/enterprise](https://dev.arcxp.com/api/subscriptions-apis)

## 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}](https://dev.arcxp.com/api/subscriptions-apis)

[GET {base\_URL}/sales/api/v1/order/search](https://dev.arcxp.com/api/subscriptions-apis)

## 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](https://dev.arcxp.com/api/subscriptions-apis)