Create a subscription

Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions.

When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request.

To start subscriptions where the first invoice always begins in a open status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.

Request

Header Params

Body Params application/json

Example

{
    "customer_id": "{{customer-id}}",
    "recurring": {
        "interval": "month",
        "interval_count": 1,
        "unit_amount": 112,
        "total_billing_cycles": 10
    },
    "currency": "USD",
    "description": "subscription desc",
    "order": {
        "category": "Apparel and accessories",
        "products": [
            {
                "desc": "IPHONE 7",
                "effective_end_at": "2020-12-31T23:59:59Z",
                "effective_start_at": "2020-01-01T00:00:00Z",
                "name": "IPHONE7",
                "quantity": 5,
                "seller": {
                    "identifier": "string",
                    "name": "string"
                },
                "sku": "100004",
                "type": "physical",
                "price": 204.65,
                "url": "https://example.airwallex.com/product/12345"
            }
        ],
        "shipping": {
            "address": {
                "country": "qui esse",
                "city": "Shanghai",
                "postcode": "100000",
                "state": "Shanghai",
                "line1": "Pudong District",
                "line2": "ad adipisicing"
            },
            "name": "Charlie Durgan",
            "phone": "(314) 890-6277",
            "first_name": "John",
            "last_name": "Doe",
            "shipping_method": "sameday"
        }
    },
    "metadata": {},
    "livemode": false,
    "prorate": true,
    "cancel_at_period_end": true,
    "current_period_end": "Duis ex pariatur",
    "current_period_start": "labore ut",
    "default_payment_method": "{{payment-method-id}}",
    "latest_invoice": {
        "id": "mmYpq8qeKMIn0YfFtUdBr",
        "collection_method": "charge_automatically",
        "currency": "dolore",
        "customer_id": "17",
        "description": "Comminor itaque cribro ventus mollitia aliqua pecto. Artificiose texo itaque conturbo minima somnus. Adsum tergeo adeptio aer vestigium brevis admitto possimus calculus apostolus. Vestrum tollo claro error adeo vobis timor colligo.",
        "metadata": {},
        "hosted_invoice_url": "https://phony-fort.net/",
        "subscription_id": "78",
        "payment_intent": {
            "id": "v660nMFHVdMC76rzCzwvm",
            "code": "67",
            "source": "quis eu amet nulla",
            "message": "consequat sunt",
            "amount": 359.65,
            "currency": "velit magna elit est",
            "status": "failed",
            "customer_id": "64",
            "customer": {
                "merchant_customer_id": "100",
                "phone": "(282) 610-6714",
                "address": {
                    "country": "sunt ea ullamco quis aliqua",
                    "city": "Shanghai",
                    "postcode": "100000",
                    "state": "Shanghai",
                    "line1": "Pudong District",
                    "line2": "Duis sed dolor magna"
                },
                "description": "Aggredior vulpes aeger bellum terebro cupio porro concido. Auxilium ultio cunctatio suasoria ut collum. Suscipit adaugeo adfero.",
                "metadata": {},
                "shipping": {
                    "address": {
                        "country": "sed ut",
                        "city": "Shanghai",
                        "postcode": "100000",
                        "state": "Shanghai",
                        "line1": "Pudong District",
                        "line2": "eu pariatur aliqua tempor esse"
                    },
                    "name": "Marie Dietrich",
                    "phone": "(867) 663-1125",
                    "first_name": "John",
                    "last_name": "Doe",
                    "shipping_method": "sameday"
                }
            },
            "description": "Vel hic deludo admoneo vicinus conatus solio. Amo copia subito assentator voluptatum. Tener tactus crebro verumtamen vere utor. Abduco pectus ustilo harum temeritas. Abundans desipio varius aut bestia necessitatibus vomito.",
            "order": {
                "category": "Apparel and accessories",
                "products": [
                    {
                        "desc": "IPHONE 7",
                        "effective_end_at": "2020-12-31T23:59:59Z",
                        "effective_start_at": "2020-01-01T00:00:00Z",
                        "name": "IPHONE7",
                        "quantity": 5,
                        "seller": {
                            "identifier": "string",
                            "name": "string"
                        },
                        "sku": "100004",
                        "type": "physical",
                        "price": 44.79,
                        "url": "https://example.com/product/12345"
                    },
                    {
                        "desc": "IPHONE 7",
                        "effective_end_at": "2020-12-31T23:59:59Z",
                        "effective_start_at": "2020-01-01T00:00:00Z",
                        "name": "IPHONE7",
                        "quantity": 5,
                        "seller": {
                            "identifier": "string",
                            "name": "string"
                        },
                        "sku": "100004",
                        "type": "physical",
                        "price": 865.95,
                        "url": "https://example.com/product/12345"
                    }
                ],
                "shipping": {
                    "address": {
                        "country": "Excepteur proident enim",
                        "city": "Shanghai",
                        "postcode": "100000",
                        "state": "Shanghai",
                        "line1": "Pudong District",
                        "line2": "in sed"
                    },
                    "name": "Leona Bergnaum",
                    "phone": "(901) 722-5977",
                    "first_name": "John",
                    "last_name": "Doe",
                    "shipping_method": "sameday"
                }
            },
            "metadata": {},
            "confirm": true,
            "auto_capture": true,
            "merchant_order_id": "58",
            "invoice_id": "100",
            "captured_amount": 529.38,
            "available_payment_method_types": [
                "laborum",
                "consectetur cupidatat cillum"
            ],
            "payment_method_options": {
                "type": "wechatpay",
                "card": {
                    "authorization_type": "dolore officia irure in",
                    "auto_capture": true,
                    "three_ds_action": "voluptate est"
                }
            },
            "cancellation_reason": "cillum enim aliquip esse aute",
            "cancelled_at": "amet officia",
            "next_action": {
                "type": "commodo exercitation reprehenderit dolore",
                "redirect": {
                    "contentType": "in laborum",
                    "method": "id cillum nulla ex aliquip",
                    "url": "https://favorable-makeover.name/"
                },
                "alipay_redirect": {
                    "native_data": "ut commodo est mollit",
                    "native_url": "https://rural-edge.biz/",
                    "return_url": "https://noteworthy-freckle.info/",
                    "url": "https://monthly-replacement.us/"
                },
                "alipay_qrcode_display": {
                    "data": "officia dolor Ut",
                    "hosted_instructions_url": "https://youthful-coil.name/",
                    "image_data_url": "https://loremflickr.com/400/400?lock=3908990962286733",
                    "image_url_png": "https://loremflickr.com/400/400?lock=1964901286578490",
                    "image_url_svg": "https://loremflickr.com/400/400?lock=161599659947788"
                },
                "oxxo_display": {
                    "expires_after": "2024-12-09 18:28:48",
                    "hosted_voucher_url": "https://judicious-chiffonier.org/",
                    "number": "31"
                },
                "boleto_display": {
                    "expires_at": "2024-12-10 12:29:24",
                    "hosted_voucher_url": "https://fortunate-riser.info/",
                    "number": "4",
                    "pdf": "sint occaecat reprehenderit"
                },
                "dcc_data": {
                    "amount": 163.49,
                    "client_rate": 58,
                    "currency": "labore",
                    "currency_pair": "exercitation anim quis in commodo",
                    "rate_expiry": "Excepteur amet ullamco veniam",
                    "rate_timestamp": "1733728977"
                },
                "data": {}
            },
            "return_url": "https://simple-supplier.info/",
            "client_secret": "commodo",
            "payment_method_id": "68",
            "mandate_id": "2025-11-30",
            "decline_code": "29",
            "doc_url": "https://dull-brush.org/"
        },
        "default_payment_method": "dolore et",
        "days_until_due": 36,
        "due_date": "2025-10-30",
        "effective_at": "irure ut ea",
        "footer": "fugiat aliqua",
        "number": "100",
        "total_amount": 575.75,
        "period_end": "enim eiusmod eu in cillum",
        "period_start": "dolor cupidatat dolore",
        "status": "draft",
        "merchant_no": "cillum qui reprehenderit in dolore",
        "app_id": "81",
        "create_at": "2024-12-17 10:59:26",
        "modify_at": "ut nisi sunt nostrud"
    },
    "first_invoice_id": "44",
    "collection_method": "charge_automatically",
    "days_until_due": 19,
    "ended_at": "exercitation mollit sint nisi",
    "invoice_now": false
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://openapi1.uat.useepay.com/api/v1/subscriptions/create' \
--header 'x-merchant-no: 500000000007245' \
--header 'x-api-key: FUYTIUvjhgfytfuytwiue' \
--header 'x-app-id: www.pay.com' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customer_id": "cus_1JA7UDDQG3800",
    "recurring": {
        "interval": "month",
        "interval_count": 1,
        "unit_amount": 112,
        "total_billing_cycles": 10
    },
    "currency": "USD",
    "description": "subscription desc",
    "order": {
        "category": "Apparel and accessories",
        "products": [
            {
                "desc": "IPHONE 7",
                "effective_end_at": "2020-12-31T23:59:59Z",
                "effective_start_at": "2020-01-01T00:00:00Z",
                "name": "IPHONE7",
                "quantity": 5,
                "seller": {
                    "identifier": "string",
                    "name": "string"
                },
                "sku": "100004",
                "type": "physical",
                "price": 204.65,
                "url": "https://example.airwallex.com/product/12345"
            }
        ],
        "shipping": {
            "address": {
                "country": "qui esse",
                "city": "Shanghai",
                "postcode": "100000",
                "state": "Shanghai",
                "line1": "Pudong District",
                "line2": "ad adipisicing"
            },
            "name": "Charlie Durgan",
            "phone": "(314) 890-6277",
            "first_name": "John",
            "last_name": "Doe",
            "shipping_method": "sameday"
        }
    },
    "metadata": {},
    "livemode": false,
    "prorate": true,
    "cancel_at_period_end": true,
    "current_period_end": "Duis ex pariatur",
    "current_period_start": "labore ut",
    "default_payment_method": "pm_1JAS4J8JK0800",
    "latest_invoice": {
        "id": "mmYpq8qeKMIn0YfFtUdBr",
        "collection_method": "charge_automatically",
        "currency": "dolore",
        "customer_id": "17",
        "description": "Comminor itaque cribro ventus mollitia aliqua pecto. Artificiose texo itaque conturbo minima somnus. Adsum tergeo adeptio aer vestigium brevis admitto possimus calculus apostolus. Vestrum tollo claro error adeo vobis timor colligo.",
        "metadata": {},
        "hosted_invoice_url": "https://phony-fort.net/",
        "subscription_id": "78",
        "payment_intent": {
            "id": "v660nMFHVdMC76rzCzwvm",
            "code": "67",
            "source": "quis eu amet nulla",
            "message": "consequat sunt",
            "amount": 359.65,
            "currency": "velit magna elit est",
            "status": "failed",
            "customer_id": "64",
            "customer": {
                "merchant_customer_id": "100",
                "phone": "(282) 610-6714",
                "address": {
                    "country": "sunt ea ullamco quis aliqua",
                    "city": "Shanghai",
                    "postcode": "100000",
                    "state": "Shanghai",
                    "line1": "Pudong District",
                    "line2": "Duis sed dolor magna"
                },
                "description": "Aggredior vulpes aeger bellum terebro cupio porro concido. Auxilium ultio cunctatio suasoria ut collum. Suscipit adaugeo adfero.",
                "metadata": {},
                "shipping": {
                    "address": {
                        "country": "sed ut",
                        "city": "Shanghai",
                        "postcode": "100000",
                        "state": "Shanghai",
                        "line1": "Pudong District",
                        "line2": "eu pariatur aliqua tempor esse"
                    },
                    "name": "Marie Dietrich",
                    "phone": "(867) 663-1125",
                    "first_name": "John",
                    "last_name": "Doe",
                    "shipping_method": "sameday"
                }
            },
            "description": "Vel hic deludo admoneo vicinus conatus solio. Amo copia subito assentator voluptatum. Tener tactus crebro verumtamen vere utor. Abduco pectus ustilo harum temeritas. Abundans desipio varius aut bestia necessitatibus vomito.",
            "order": {
                "category": "Apparel and accessories",
                "products": [
                    {
                        "desc": "IPHONE 7",
                        "effective_end_at": "2020-12-31T23:59:59Z",
                        "effective_start_at": "2020-01-01T00:00:00Z",
                        "name": "IPHONE7",
                        "quantity": 5,
                        "seller": {
                            "identifier": "string",
                            "name": "string"
                        },
                        "sku": "100004",
                        "type": "physical",
                        "price": 44.79,
                        "url": "https://example.com/product/12345"
                    },
                    {
                        "desc": "IPHONE 7",
                        "effective_end_at": "2020-12-31T23:59:59Z",
                        "effective_start_at": "2020-01-01T00:00:00Z",
                        "name": "IPHONE7",
                        "quantity": 5,
                        "seller": {
                            "identifier": "string",
                            "name": "string"
                        },
                        "sku": "100004",
                        "type": "physical",
                        "price": 865.95,
                        "url": "https://example.com/product/12345"
                    }
                ],
                "shipping": {
                    "address": {
                        "country": "Excepteur proident enim",
                        "city": "Shanghai",
                        "postcode": "100000",
                        "state": "Shanghai",
                        "line1": "Pudong District",
                        "line2": "in sed"
                    },
                    "name": "Leona Bergnaum",
                    "phone": "(901) 722-5977",
                    "first_name": "John",
                    "last_name": "Doe",
                    "shipping_method": "sameday"
                }
            },
            "metadata": {},
            "confirm": true,
            "auto_capture": true,
            "merchant_order_id": "58",
            "invoice_id": "100",
            "captured_amount": 529.38,
            "available_payment_method_types": [
                "laborum",
                "consectetur cupidatat cillum"
            ],
            "payment_method_options": {
                "type": "wechatpay",
                "card": {
                    "authorization_type": "dolore officia irure in",
                    "auto_capture": true,
                    "three_ds_action": "voluptate est"
                }
            },
            "cancellation_reason": "cillum enim aliquip esse aute",
            "cancelled_at": "amet officia",
            "next_action": {
                "type": "commodo exercitation reprehenderit dolore",
                "redirect": {
                    "contentType": "in laborum",
                    "method": "id cillum nulla ex aliquip",
                    "url": "https://favorable-makeover.name/"
                },
                "alipay_redirect": {
                    "native_data": "ut commodo est mollit",
                    "native_url": "https://rural-edge.biz/",
                    "return_url": "https://noteworthy-freckle.info/",
                    "url": "https://monthly-replacement.us/"
                },
                "alipay_qrcode_display": {
                    "data": "officia dolor Ut",
                    "hosted_instructions_url": "https://youthful-coil.name/",
                    "image_data_url": "https://loremflickr.com/400/400?lock=3908990962286733",
                    "image_url_png": "https://loremflickr.com/400/400?lock=1964901286578490",
                    "image_url_svg": "https://loremflickr.com/400/400?lock=161599659947788"
                },
                "oxxo_display": {
                    "expires_after": "2024-12-09 18:28:48",
                    "hosted_voucher_url": "https://judicious-chiffonier.org/",
                    "number": "31"
                },
                "boleto_display": {
                    "expires_at": "2024-12-10 12:29:24",
                    "hosted_voucher_url": "https://fortunate-riser.info/",
                    "number": "4",
                    "pdf": "sint occaecat reprehenderit"
                },
                "dcc_data": {
                    "amount": 163.49,
                    "client_rate": 58,
                    "currency": "labore",
                    "currency_pair": "exercitation anim quis in commodo",
                    "rate_expiry": "Excepteur amet ullamco veniam",
                    "rate_timestamp": "1733728977"
                },
                "data": {}
            },
            "return_url": "https://simple-supplier.info/",
            "client_secret": "commodo",
            "payment_method_id": "68",
            "mandate_id": "2025-11-30",
            "decline_code": "29",
            "doc_url": "https://dull-brush.org/"
        },
        "default_payment_method": "dolore et",
        "days_until_due": 36,
        "due_date": "2025-10-30",
        "effective_at": "irure ut ea",
        "footer": "fugiat aliqua",
        "number": "100",
        "total_amount": 575.75,
        "period_end": "enim eiusmod eu in cillum",
        "period_start": "dolor cupidatat dolore",
        "status": "draft",
        "merchant_no": "cillum qui reprehenderit in dolore",
        "app_id": "81",
        "create_at": "2024-12-17 10:59:26",
        "modify_at": "ut nisi sunt nostrud"
    },
    "first_invoice_id": "44",
    "collection_method": "charge_automatically",
    "days_until_due": 19,
    "ended_at": "exercitation mollit sint nisi",
    "invoice_now": false
}'

Responses

🟢200Success

application/json

Body

Example

{
    "id": "sub_1JBPC9HT80000",
    "recurring": {
        "interval": "month",
        "interval_count": 1,
        "unit_amount": 112,
        "total_billing_cycles": 10
    },
    "currency": "USD",
    "description": "subscription desc",
    "order": {
        "category": "Apparel and accessories",
        "products": [
            {
                "category": "Apparel and accessories",
                "code": "3414314111",
                "desc": "IPHONE 7",
                "effective_end_at": "2020-12-31T23:59:59Z",
                "effective_start_at": "2020-01-01T00:00:00Z",
                "name": "IPHONE7",
                "quantity": 5,
                "seller": {
                    "identifier": "string",
                    "name": "string"
                },
                "sku": "100004",
                "type": "physical",
                "unit_price": 100.01,
                "url": "https://example.useepay.com/product/12345"
            }
        ],
        "shipping": {
            "address": {
                "city": "Shanghai",
                "country_code": "CN",
                "postcode": "100000",
                "state": "Shanghai",
                "line1": "Pudong District"
            },
            "first_name": "John",
            "last_name": "Doe",
            "phone_number": "13800000000",
            "shipping_method": "sameday"
        }
    },
    "metadata": {
        "sid": "0001"
    },
    "status": "incomplete",
    "livemode": null,
    "prorate": null,
    "merchant_no": "500000000007264",
    "app_id": "www.demo.com",
    "create_at": "2024-10-28T03:49:28Z",
    "modify_at": "2024-10-28T03:49:28Z",
    "customer_id": "cus_1JA7UDDQG3800",
    "cancel_at_period_end": null,
    "current_period_end": null,
    "current_period_start": null,
    "latest_invoice": null,
    "first_invoice_id": null,
    "cancel_at": null,
    "canceled_at": null,
    "collection_method": "charge_automatically",
    "days_until_due": null,
    "ended_at": null,
    "cancellation_details": null,
    "invoice_now": null
}