# Subscriptions API # Overview * **Version:** 2.0 * **Servers**: `https://api.xsolla.com/merchant/v2/` This API reference describes endpoints for managing subscriptions, coupons, and promotions. To get more information about Subscriptions, see the [product guide](https://developers.xsolla.com/doc/subscriptions) and the [glossary](https://developers.xsolla.com/doc/subscriptions/integration-guide/get-started/#general_glossary). Version: 2.0 ## Security ### basicAuth Xsolla API uses basic access authentication. All requests to API must contain the `Authorization: Basic ` header, where `` is the `merchant_id:api_key` pair encoded according to the Base64 standard. Go to [Publisher Account](https://publisher.xsolla.com/) to find these parameters:
For more information about working with API keys, see the [API reference](https://developers.xsolla.com/api/getting-started/#api_keys_overview). Type: http Scheme: basic ### subscriptionsManagementJwtAuth Type: http Scheme: bearer ## Download OpenAPI description [Subscriptions API](https://developers.xsolla.com/_bundle/api/subscriptions/index.yaml) ## Token ### Create token - [POST /merchants/{merchant_id}/token](https://developers.xsolla.com/api/subscriptions/token/create-token.md): You can create a token with arbitrary user parameters. You send these parameters when obtaining the token and receive them back after a successful payment. A token can only contain parameters either described in this document or predefined by you. If any parameter is sent in the wrong format or has the wrong type, no token will be issued. You will receive a 422 HTTP code with the error description in the JSON body. In extended_message you will receive an information what exact parameters have been sent incorrectly. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ## Plans ### Create Plan - [POST /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/api/subscriptions/plans/create-plan.md): Creates a subscription plan. ### Get Plans - [GET /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/api/subscriptions/plans/get-plans.md): Lists all subscription plans. ### Update Plan - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/api/subscriptions/plans/update-plan-parameters.md): Updates subscription plan parameters. ### Enable Plan - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/api/subscriptions/plans/enable-plan.md): Enables a subscription plan. ### Disable Plan - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/api/subscriptions/plans/disable-plan.md): Disables a subscription plan. ### Delete Plan - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://developers.xsolla.com/api/subscriptions/plans/delete-plan.md): Deletes a subscription plan. ## Products ### Create Product - [POST /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/api/subscriptions/products/create-product.md): Creates a subscription-based product. ### Get Products - [GET /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/api/subscriptions/products/get-products.md): Lists all subscription-based products. ### Update Product - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/api/subscriptions/products/update-product.md): Updates a subscription-based product. ### Delete Product - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/api/subscriptions/products/delete-product.md): Deletes a subscription-based product. ## Subscription management ### Get Subscription - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/api/subscriptions/subscriptions/get-subscription.md): Gets a specific subscription details by ID. ### Update Subscription - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/api/subscriptions/subscriptions/update-subscription.md): Updates a subscription by either changing its status (active, canceled, or non_renewing) or postponing the next billing date. ### Get Subscriptions - [GET /merchants/{merchant_id}/subscriptions](https://developers.xsolla.com/api/subscriptions/subscriptions/get-subscriptions.md): Lists all recurrent subscriptions.NoticeThis API method can’t be used under a high load. The maximum load is 20 requests per minute. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ## Payments ### Get Payments - [GET /projects/{project_id}/subscriptions/payments](https://developers.xsolla.com/api/subscriptions/payments/get-payments.md): Lists all subscription payments. ### Get User Payments - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://developers.xsolla.com/api/subscriptions/payments/get-user-payments.md): Lists all payments made by a specific user. ### Get Currencies - [GET /projects/{project_id}/subscriptions/currencies](https://developers.xsolla.com/api/subscriptions/payments/get-currencies.md): Lists all supported subscription currencies. ## Promotions ### Create Promotion - [POST /merchants/{merchant_id}/promotions](https://developers.xsolla.com/api/subscriptions/promotions/create-promotion.md): Create a new promotion. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Promotions List - [GET /merchants/{merchant_id}/promotions](https://developers.xsolla.com/api/subscriptions/promotions/get-promotions-list.md): List of all promotions. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Promotion - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/api/subscriptions/promotions/get-promotion.md): Retrieves a promotion. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Update Promotion - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/api/subscriptions/promotions/update-promotion.md): Updates a promotion. If the promotion is read-only (read_only = true), you are not allowed to change project_id parameter. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Delete Promotion - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/api/subscriptions/promotions/delete-promotion.md): Deletes a promotion. You can only delete promotions with enabled = false. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Review Promotion - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://developers.xsolla.com/api/subscriptions/promotions/review-promotion.md): You need to review a promotion before activating it. This method returns the list of errors, if any. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Set Rewards - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/api/subscriptions/promotions/set-rewards.md): Sets the rewards for a promotion. If the promotion is read-only (read_only = true), you cannot update the rewards. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Rewards - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/api/subscriptions/promotions/get-rewards.md): Gets the list of rewards associated with a promotion. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Toggle Promotion - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://developers.xsolla.com/api/subscriptions/promotions/toggle-promotion.md): Toggles the status of a promotion from enabled to disabled and vice versa. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Set Subject - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/api/subscriptions/promotions/set-subject.md): Sets the subject of a promotion. If the promotion is read-only (read_only = true), you cannot update the subject. The subject can take the following values: purchase, or items, or packages. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Subject - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/api/subscriptions/promotions/get-subject.md): Gets information on the subject of a promotion. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Set Payment Systems - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://developers.xsolla.com/api/subscriptions/promotions/set-payment-systems.md): Sets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems. If the promotion is read-only (read_only = true), you cannot call this method. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Payment Systems - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://developers.xsolla.com/api/subscriptions/promotions/get-payment-systems.md): Gets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Set Validity Periods - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/api/subscriptions/promotions/set-validity-periods.md): Sets date/time ranges when a promotion is valid. If the promotion is read-only (read_only = true), you cannot edit existing periods, but you can add new ones. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Get Validity Periods - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/api/subscriptions/promotions/get-validity-periods.md): Gets date/time ranges when a promotion is valid. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ## Coupons ### Get Coupon - [GET /projects/{project_id}/coupons/{code}/details](https://developers.xsolla.com/api/subscriptions/coupons/get-coupon.md): Get coupon details by its code. ### Redeem Coupon - [POST /projects/{project_id}/coupons/{code}/redeem](https://developers.xsolla.com/api/subscriptions/coupons/redeem-coupon.md): Redeem a coupon by its code. ### Create Campaign - [POST /merchants/{merchant_id}/coupon_promotions](https://developers.xsolla.com/api/subscriptions/coupons/create-campaign.md): Create a new coupon campaign. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Add Coupon to Campaign - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://developers.xsolla.com/api/subscriptions/coupons/add-coupon-to-campaign.md): Add a coupon code to a coupon campaign. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ### Attach Campaign to Promotion - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://developers.xsolla.com/api/subscriptions/coupons/attach-campaign-to-promotion.md): Attach a coupon campaign to a specific promotion. NoticeThis API call does not contain the project_id path-parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization. ## Subscription management ### List subscriptions - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://developers.xsolla.com/api/subscriptions/subscription-management/list-subscriptions.md) ### Get subscription - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/api/subscriptions/subscription-management/get-management-subscription.md) ### Cancel subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://developers.xsolla.com/api/subscriptions/subscription-management/cancel-subscription.md) ### Get payment account - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://developers.xsolla.com/api/subscriptions/subscription-management/get-payment-account.md) ### Activate subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://developers.xsolla.com/api/subscriptions/subscription-management/activate-subscription.md) ### Get change plan link - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://developers.xsolla.com/api/subscriptions/subscription-management/get-change-plan-link.md) ### List plans for change - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://developers.xsolla.com/api/subscriptions/subscription-management/list-plans-for-change.md) ### Get plan for change - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}](https://developers.xsolla.com/api/subscriptions/subscription-management/get-plan-for-change.md) ### Manage payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://developers.xsolla.com/api/subscriptions/subscription-management/manage-payment-account.md) ### Get management settings - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://developers.xsolla.com/api/subscriptions/subscription-management/get-management-settings.md) ### List payment accounts - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/api/subscriptions/subscription-management/list-payment-accounts.md) ### Link payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/api/subscriptions/subscription-management/link-payment-account.md) ### Unlink payment account - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://developers.xsolla.com/api/subscriptions/subscription-management/unlink-payment-account.md)