/v1/subscriptions

Request for subscription creation.

The request is used to create a subscription and and obtain a link to start it.

Request

POST

https://pay.yandex.ru/api/merchant/v1/subscriptions

Production

POST

https://sandbox.pay.yandex.ru/api/merchant/v1/subscriptions

Sandbox

Body

application/json

{
    "cart": {
        "externalId": "string",
        "items": [
            {
                "description": "string",
                "discountedUnitPrice": "123.45",
                "pointsAmount": "123.45",
                "productId": "string",
                "quantity": {
                    "available": "123.45",
                    "count": "123.45",
                    "label": "string"
                },
                "receipt": {
                    "agent": {
                        "agentType": 1,
                        "operation": "string",
                        "paymentsOperator": {
                            "phones": [
                                "string"
                            ]
                        },
                        "phones": [
                            "string"
                        ],
                        "transferOperator": {
                            "address": "string",
                            "inn": "string",
                            "name": "string",
                            "phones": [
                                "string"
                            ]
                        }
                    },
                    "excise": "123.45",
                    "markQuantity": {
                        "denominator": 0,
                        "numerator": 0
                    },
                    "measure": 0,
                    "paymentMethodType": 1,
                    "paymentSubjectType": 1,
                    "productCode": "string",
                    "supplier": {
                        "inn": "string",
                        "name": "string",
                        "phones": [
                            "string"
                        ]
                    },
                    "tax": 1,
                    "title": "string"
                },
                "subtotal": "123.45",
                "title": "string",
                "total": "123.45",
                "unitPrice": "123.45"
            }
        ],
        "total": {
            "amount": "123.45",
            "label": "string",
            "pointsAmount": "123.45"
        }
    },
    "currencyCode": "RUB",
    "futureWriteOffAmount": "123.45",
    "intervalCount": 0,
    "intervalUnit": "SECOND",
    "isBinding": false,
    "metadata": "string",
    "orderId": "string",
    "orderSource": "WEBSITE",
    "purpose": "string",
    "redirectUrls": {
        "onAbort": "string",
        "onError": "string",
        "onSuccess": "string"
    },
    "title": "string",
    "trialCount": 0,
    "trialEndAt": "2022-12-29T18:02:01Z",
    "trialUnit": "SECOND",
    "ttl": 1800
}

Name	Description
currencyCode*	Type: string Three-letter code of the order currency code (ISO 4217) Max length: `2048` Enum: `RUB`
orderId*	Type: string Order ID on the merchant side (it should be unique). Further interaction on the payment request will be carried out using this ID. The ID will also be used at reconciliation Max length: `2048`
cart	Type: RenderedCart Cart
futureWriteOffAmount	Type: string<double> Amount to be debited in the future Example: `123.45`
intervalCount	Type: integer<int32> The number of subscription periods, such as "debit every 6 months" Required if `isBinding=True` is not specified
intervalUnit	Type: string Subscription frequency time unit Required if `isBinding=True` is not specified Enum: `SECOND`, `DAY`, `WEEK`, `MONTH`, `YEAR`, `null`
isBinding	Type: boolean Allows linking the user's card with no items added to the cart If the first time a payment is debited only requires the card binding, pass `isBinding=true`` in your request. No cart items and subscription frequency need to be passed in this scenario. Default: `false`
metadata	Type: string Arbitrary order data for internal use Max length: `2048`
orderSource	Type: string Indicates where order creation was initialized Used for subsequent analysis WEBSITE: The button is placed on the website. A payment link is generated after certain user actions (clicking the button) on the website APP: The button is placed in the mobile app. A payment link is generated after certain user actions (tapping the button) in the app CRM: A payment link is generated by a manager in the CRM system or another admin panel CASH_REGISTER: A payment link is generated to be displayed in the offline cash register CMS_PLUGIN: The payment link is generated in the CMS plugin. Default: `null` Enum: `WEBSITE`, `APP`, `CRM`, `CASH_REGISTER`, `CMS_PLUGIN`
purpose	Type: string Purpose of payment Max length: `1000`
redirectUrls	Type: MerchantRedirectUrls Links for redirecting the user from the payment form. Required for online stores
title	Type: string Subscription name Max length: `30`
trialCount	Type: integer<int32> The number of periods in a trial period, such as "7 days"
trialEndAt	Type: string<date-time> Trial period end date. Mutually exclusive with the `trial_unit` + `trial_count` fields
trialUnit	Type: string Time unit of the trial period frequency Enum: `SECOND`, `DAY`, `WEEK`, `MONTH`, `YEAR`, `null`
ttl	Type: integer<int32> Order time-to-live (seconds) `180 <= ttl <= 604800` Default: `1800`

RenderedCart

Name	Description
items*	Type: RenderedCartItem[] Cart items that the customer pays for.
total*	Type: CartTotal Final order cost.
externalId	Type: string Cart ID passed by the merchant Max length: `2048`

MerchantRedirectUrls

Name	Description
onError*	Type: string The field is required for online stores only. A link to redirect the user in case of a payment error or TTL expiry for a payment link Max length: `2048`
onSuccess*	Type: string The field is required for online stores only. Link to redirect the user on payment success. Max length: `2048`
onAbort	Type: string Link to redirect the user on payment cancellation. Payment can be canceled by the user in the payment form. Max length: `2048`

RenderedCartItem

Name	Description
productId*	Type: string Product ID in the merchant system Make sure that each `productId` in the request parameters is unique. Max length: `2048`
quantity*	Type: ItemQuantity Product quantity in the order
title*	Type: string Product name Max length: `2048`
total*	Type: string<double> Total price per item with item discount Example: `123.45`
description	Type: string Product description Max length: `2048`
discountedUnitPrice	Type: string<double> Price per product unit with discount per item Example: `123.45`
pointsAmount	Type: string<double> Number of Plus points Read-only field. Input values will be ignored. Example: `123.45`
receipt	Type: ItemReceipt Data for receipt generation
subtotal	Type: string<double> Total price per item without discount Example: `123.45`
unitPrice	Type: string<double> Total price per product unit without discount Example: `123.45`

CartTotal

Name	Description
amount*	Type: string<double> Cart cost with all discounts Example: `123.45`
label	Type: string Name of measurement units, for example, "kg" or "pcs" Max length: `2048`
pointsAmount	Type: string<double> Number of Plus points Read-only field. Input values will be ignored. Example: `123.45`

ItemQuantity

Name	Description
count*	Type: string<double> Product quantity in the order Example: `123.45`
available	Type: string<double> Maximum available product quantity Example: `123.45`
label	Type: string Name of measurement units, for example, "kg" or "pcs" Max length: `2048`

ItemReceipt

Name	Description
tax*	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`
agent	Type: Agent
excise	Type: string<double> It shouldn't include more than two decimal digits. For example: 1.12, 5.1, 10, 11.00 . Example: `123.45`
markQuantity	Type: MarkQuantity
measure	Type: integer Value description: Link Enum: `0`, `10`, `11`, `12`, `20`, `21`, `22`, `30`, `31`, `32`, `40`, `41`, `42`, `50`, `51`, `70`, `71`, `72`, `73`, `80`, `81`, `82`, `83`, `255`, `null`
paymentMethodType	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `null`
paymentSubjectType	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `null`
productCode	Type: string<base64> Product code (a base64-encoded array of 1 to 32 bytes)
supplier	Type: Supplier
title	Type: string Max length: `2048`

Agent

Name	Description
agentType*	Type: integer Agent type by taxable object. See values Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`
operation	Type: string Max length: `2048`
paymentsOperator	Type: PaymentsOperator
phones	Type: string[] Max length: `2048`
transferOperator	Type: TransferOperator

MarkQuantity

Name	Description
denominator*	Type: integer<int32>
numerator*	Type: integer<int32>

Supplier

Name	Description
inn	Type: string Max length: `2048`
name	Type: string Max length: `2048`
phones	Type: string[] Max length: `2048`

PaymentsOperator

Name

Description

phones

Type: string[]

Max length: 2048

TransferOperator

Name	Description
address	Type: string Max length: `2048`
inn	Type: string Max length: `2048`
name	Type: string Max length: `2048`
phones	Type: string[] Max length: `2048`

Responses

200 OK

Body

application/json

{
    "code": 200,
    "data": {
        "paymentUrl": "string",
        "subscriptionId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b"
    },
    "status": "success"
}

Name	Description
data*	Type: CreateSubscriptionResponseData
code	Type: number Default: `200`
status	Type: string Default: `success` Enum: `success`

CreateSubscriptionResponseData

Name

Description

paymentUrl*

Type: string

Link to paying for the order

Max length: 2048

subscriptionId*

Type: string<uuid>

Subscription ID

Max length: 2048

Was the article helpful?

Overview

/v1/subscriptions/recur