---
updatedAt: 2026-07-14T18:06:59.000Z
agentTools:
projectIndex: https://docs.asaas.com/llms.txt
---
# Create new subscription
### Subscriptions Guide
[Check the subscriptions guide for more information.](https://docs.asaas.com/docs/subscription-overview)
Endpoint responsible for creating a new recurring subscription in Asaas.
A subscription works as a charge scheduler, automatically creating new charges according to the configured periodicity. This resource is indicated for monthly fees, plans, SaaS subscriptions, service contracts, and any other scenario in which there is recurring payment.
After the subscription is created, the charges will be generated automatically until the subscription is removed or reaches the defined limit.
***
## When to use
Use this endpoint when your application needs to:
* create recurring charges automatically;
* charge customers at periodic intervals;
* manage product or service subscriptions;
* automate recurring billing;
* use bank slip, Pix, or credit card as the payment method.
***
## Main request parameters
Some fields play a fundamental role in the subscription behavior:
* **customer** — identifier of the customer who will be charged.
* **billingType** — defines the payment method used in recurring charges.
* **value** — value of each subscription charge.
* **nextDueDate** — defines the due date of the first charge.
* **cycle** — determines the periodicity of the charges.
* **endDate** — deadline for generating new charges.
* **maxPayments** — maximum number of charges that can be created.
* **externalReference** — subscription identifier in the source system.
* **split** — configures the automatic division of amounts, when applicable.
* **callback** — configures the redirect after payment, when supported by the flow.
### **Important**
The complete request parameters are automatically documented in this reference.
This section highlights only the fields that have the greatest impact on the subscription behavior.
***
## Important business rules
When creating a subscription:
* the first charge will be created using the date informed in `nextDueDate`;
* the next charges will be generated automatically according to the periodicity informed in `cycle`;
* the value of each charge will be defined by the `value` parameter;
* the subscription remains active until it is removed or reaches `endDate` or `maxPayments`, when informed;
* each created charge has its own lifecycle and can be monitored individually.
If you use credit card, card validation occurs during subscription creation, but the charge will only be performed on the due date of each recurring charge.
***
## Trial period
If your application works with a trial period (for example, 7 free days), simply inform in `nextDueDate` the date on which the first charge should occur.
Example:
* subscription created today;
* `nextDueDate` configured for 7 days from now;
* first charge will be generated with due date on that date.
If the credit card is informed during subscription creation, it will be validated and stored for automatic use on the first due date.
***
## Behavior when informing the card later
If the subscription is created without the credit card data and the payer later informs a valid card, the behavior will be different.
In this scenario, the amount of the pending charge will be processed immediately after the card is registered, regardless of the date originally informed in `nextDueDate`.
This behavior exists to allow the immediate regularization of the charge that was waiting for a valid payment method.
***
## How the flow works
In a typical integration, subscription creation follows the following journey:
```text
Create subscription
↓
Subscription created
↓
Generate charges automatically
↓
Customer makes the payment
↓
Webhook informs the result
↓
Application updates the status
```
Charges are generated automatically by the subscription and each one has its own financial lifecycle.
***
## Best practices
### **Recommended**
- Store the subscription identifier returned by the API.
- Use `externalReference` to relate the subscription to your system.
- Monitor the events sent by Webhook to track each created charge.
- Do not use only subscription creation as payment confirmation.
- Correctly define `nextDueDate`, considering possible trial periods.
***
## Operational impacts
Subscription creation does not represent receipt of payment.
Each charge will be created automatically according to the periodicity configured in `cycle` and must be monitored individually through the API or Webhooks.
Subsequent changes to the subscription may affect only future charges or, when supported by the operation, also pending charges.
***
## Next steps
After creating a subscription, the integration usually proceeds to:
* Retrieve a subscription.
* Update a subscription.
* List charges of a subscription.
* Configure Webhooks.
* Manage recurring charges.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "Asaas",
"description": "API pública de integração com a plataforma Asaas.",
"version": "3.0.0"
},
"servers": [
{
"url": "https://api-sandbox.asaas.com",
"description": "Sandbox"
}
],
"security": [
{
"Authorization": []
}
],
"tags": [
{
"name": "Subscription"
}
],
"paths": {
"/v3/subscriptions": {
"post": {
"tags": [
"Subscription"
],
"summary": "Create new subscription",
"description": "",
"operationId": "create-new-subscription",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionSaveRequestDTO"
}
}
}
},
"responses": {
"200": {
"description": "Ok",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionGetResponseDTO"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseDTO"
},
"example": {
"errors": [
{
"code": "error_code",
"description": "Error description"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponseDTO"
},
"example": {
"errors": [
{
"code": "invalid_access_token",
"description": "A chave de API fornecida é inválida"
}
]
}
}
}
}
},
"deprecated": false
}
}
},
"components": {
"schemas": {
"ErrorResponseDTO": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"description": "List of objects",
"deprecated": false,
"items": {
"$ref": "#/components/schemas/ErrorResponseItemDTO"
}
}
}
},
"ErrorResponseItemDTO": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"deprecated": false,
"example": null
},
"description": {
"type": "string",
"description": "Error description",
"deprecated": false,
"example": null
}
},
"description": "List of objects",
"deprecated": false
},
"PaymentDiscountDTO": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Percentage or fixed amount of discount to be applied to the Payment amount",
"example": 10,
"deprecated": false
},
"dueDateLimitDays": {
"type": "integer",
"description": "Days before expiration to apply discount. Ex: 0 = until expiration, 1 = up to one day before, 2 = up to 2 days before, and so on",
"format": "int32",
"example": 0,
"deprecated": false
},
"type": {
"$ref": "#/components/schemas/PaymentDiscountDiscountType"
}
},
"description": "Discount information",
"deprecated": false
},
"PaymentDiscountDiscountType": {
"type": "string",
"description": "Discount type",
"example": "PERCENTAGE",
"deprecated": false,
"enum": [
"FIXED",
"PERCENTAGE"
]
},
"PaymentInterestRequestDTO": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Percentage of interest per month on the amount charged for payment after maturity",
"deprecated": false,
"example": null
}
},
"description": "Interest information for payment after due date",
"deprecated": false
},
"PaymentFineRequestDTO": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Percentage of fine on the amount of the charge for payment after the due date",
"deprecated": false,
"example": null
},
"type": {
"$ref": "#/components/schemas/PaymentFineRequestFineType"
}
},
"description": "Fine information for payment after due date",
"deprecated": false
},
"PaymentFineRequestFineType": {
"type": "string",
"description": "Fine type",
"example": "FIXED",
"deprecated": false,
"enum": [
"FIXED",
"PERCENTAGE"
]
},
"PaymentCallbackRequestDTO": {
"required": [
"successUrl"
],
"type": "object",
"properties": {
"successUrl": {
"maxLength": 255,
"type": "string",
"description": "URL that the customer will be redirected to after successful payment of the invoice or payment link",
"nullable": false,
"deprecated": false,
"example": null
},
"autoRedirect": {
"type": "boolean",
"description": "Define whether the customer will be automatically redirected or will just be informed with a button to return to the website. The default is true, if you want to disable it, enter false",
"deprecated": false,
"example": null
}
},
"description": "Automatic redirection information after the payment of the link payment",
"deprecated": false
},
"PaymentFineResponseDTO": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Fine amount in percentage",
"example": 1,
"deprecated": false
}
},
"description": "Fine information for payment after due date",
"deprecated": false
},
"PaymentInterestResponseDTO": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "Interest value in percentage",
"example": 2,
"deprecated": false
}
},
"description": "Interest information for payment after due date",
"deprecated": false
},
"SubscriptionGetResponseDTO": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "Object type",
"example": "subscription",
"deprecated": false
},
"id": {
"type": "string",
"description": "Unique subscription identifier in Asaas",
"example": "sub_VXJBYgP2u0eO",
"deprecated": false
},
"dateCreated": {
"type": "string",
"description": "Subscription creation date",
"format": "date",
"example": "2017-03-17",
"deprecated": false
},
"customer": {
"type": "string",
"description": "Unique customer identifier",
"example": "cus_0T1mdomVMi39",
"deprecated": false
},
"paymentLink": {
"type": "string",
"description": "Unique identifier of the payments link to which the subscription belongs",
"deprecated": false,
"example": null
},
"billingType": {
"$ref": "#/components/schemas/SubscriptionGetResponseBillingType"
},
"cycle": {
"$ref": "#/components/schemas/SubscriptionGetResponseCycle"
},
"value": {
"type": "number",
"description": "Subscription value",
"example": 19.9,
"deprecated": false
},
"nextDueDate": {
"type": "string",
"description": "Due date of the next payment to be generated",
"format": "date",
"example": "2017-06-15",
"deprecated": false
},
"endDate": {
"type": "string",
"description": "Deadline for payments to be due",
"format": "date",
"example": "2018-06-15",
"deprecated": false
},
"description": {
"type": "string",
"description": "Subscription description",
"example": "Pro Plan Subscription",
"deprecated": false
},
"status": {
"$ref": "#/components/schemas/SubscriptionGetResponseSubscriptionStatus"
},
"discount": {
"$ref": "#/components/schemas/PaymentDiscountDTO"
},
"fine": {
"$ref": "#/components/schemas/PaymentFineResponseDTO"
},
"interest": {
"$ref": "#/components/schemas/PaymentInterestResponseDTO"
},
"deleted": {
"type": "boolean",
"description": "Informs if the subscription has been removed",
"example": false,
"deprecated": false
},
"maxPayments": {
"type": "integer",
"description": "Maximum number of payments to be generated for this subscription",
"format": "int32",
"example": 12,
"deprecated": false
},
"externalReference": {
"type": "string",
"description": "Subscription identifier on your system",
"deprecated": false,
"example": null
},
"checkoutSession": {
"type": "string",
"description": "Unique checkout identifier",
"example": "356eb0c4-9eb7-4b7f-b2be-d9479af1d29f",
"deprecated": false
},
"split": {
"type": "array",
"description": "Split information",
"deprecated": false,
"items": {
"$ref": "#/components/schemas/SubscriptionSplitResponseDTO"
}
}
}
},
"SubscriptionGetResponseBillingType": {
"type": "string",
"description": "Billing type",
"example": "BOLETO",
"deprecated": false,
"enum": [
"UNDEFINED",
"BOLETO",
"CREDIT_CARD",
"DEBIT_CARD",
"TRANSFER",
"DEPOSIT",
"PIX"
]
},
"SubscriptionGetResponseCycle": {
"type": "string",
"description": "Billing frequency",
"example": "MONTHLY",
"deprecated": false,
"enum": [
"WEEKLY",
"BIWEEKLY",
"MONTHLY",
"BIMONTHLY",
"QUARTERLY",
"SEMIANNUALLY",
"YEARLY"
]
},
"SubscriptionGetResponseSubscriptionStatus": {
"type": "string",
"description": "Subscription status",
"example": "ACTIVE",
"deprecated": false,
"enum": [
"ACTIVE",
"EXPIRED",
"INACTIVE"
]
},
"SubscriptionSplitResponseDTO": {
"type": "object",
"properties": {
"walletId": {
"type": "string",
"description": "Asaas wallet identifier that will be transferred",
"example": "7bafd95a-e783-4a62-9be1-23999af742c6",
"deprecated": false
},
"fixedValue": {
"type": "number",
"description": "Fixed amount to be transferred to the account when the payment is received",
"example": 20.32,
"deprecated": false
},
"percentualValue": {
"type": "number",
"description": "Percentage of the net value of the charge to be transferred when received",
"deprecated": false,
"example": null
},
"externalReference": {
"type": "string",
"description": "Split identifier in your system",
"deprecated": false,
"example": null
},
"description": {
"type": "string",
"description": "Split description",
"deprecated": false,
"example": null
},
"status": {
"$ref": "#/components/schemas/SubscriptionSplitResponseSubscriptionSplitStatus"
},
"disabledReason": {
"$ref": "#/components/schemas/SubscriptionSplitResponseSubscriptionSplitDisabledReason"
}
},
"description": "Split information",
"deprecated": false
},
"SubscriptionSplitResponseSubscriptionSplitStatus": {
"type": "string",
"description": "Subscription split status",
"example": "ACTIVE",
"deprecated": false,
"enum": [
"ACTIVE",
"DISABLED"
]
},
"SubscriptionSplitResponseSubscriptionSplitDisabledReason": {
"type": "string",
"description": "Reason why subscription split was disabled",
"example": "WALLET_UNABLE_TO_RECEIVE",
"deprecated": false,
"enum": [
"WALLET_UNABLE_TO_RECEIVE",
"VALUE_DIVERGENCE",
"WALLET_REMOVED_FROM_OUTSIDE_ARRANGEMENT_ALLOW_LIST"
]
},
"SubscriptionSaveRequestDTO": {
"required": [
"customer",
"billingType",
"value",
"nextDueDate",
"cycle"
],
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Unique customer identifier in Asaas",
"nullable": false,
"example": "cus_0T1mdomVMi39",
"deprecated": false
},
"billingType": {
"$ref": "#/components/schemas/SubscriptionSaveRequestBillingType"
},
"value": {
"type": "number",
"description": "Subscription value",
"nullable": false,
"example": 19.9,
"deprecated": false
},
"nextDueDate": {
"type": "string",
"description": "First payment due",
"format": "date",
"nullable": false,
"example": "2017-05-15",
"deprecated": false
},
"discount": {
"$ref": "#/components/schemas/PaymentDiscountDTO"
},
"interest": {
"$ref": "#/components/schemas/PaymentInterestRequestDTO"
},
"fine": {
"$ref": "#/components/schemas/PaymentFineRequestDTO"
},
"cycle": {
"$ref": "#/components/schemas/SubscriptionSaveRequestCycle"
},
"description": {
"type": "string",
"description": "Subscription description (max. 500 characters)",
"example": "Pro Plan Subscription",
"deprecated": false
},
"endDate": {
"type": "string",
"description": "Deadline for payments to be due",
"format": "date",
"deprecated": false,
"example": null
},
"maxPayments": {
"type": "integer",
"description": "Maximum number of payments to be generated for this subscription",
"format": "int32",
"deprecated": false,
"example": null
},
"externalReference": {
"type": "string",
"description": "Subscription identifier on your system",
"deprecated": false,
"example": null
},
"split": {
"type": "array",
"description": "Split information",
"deprecated": false,
"items": {
"$ref": "#/components/schemas/SubscriptionSplitRequestDTO"
}
},
"callback": {
"$ref": "#/components/schemas/PaymentCallbackRequestDTO"
}
}
},
"SubscriptionSaveRequestBillingType": {
"type": "string",
"description": "Billing type",
"nullable": false,
"example": "BOLETO",
"deprecated": false,
"enum": [
"UNDEFINED",
"BOLETO",
"CREDIT_CARD",
"PIX"
]
},
"SubscriptionSaveRequestCycle": {
"type": "string",
"description": "Billing frequency",
"nullable": false,
"example": "MONTHLY",
"deprecated": false,
"enum": [
"WEEKLY",
"BIWEEKLY",
"MONTHLY",
"BIMONTHLY",
"QUARTERLY",
"SEMIANNUALLY",
"YEARLY"
]
},
"SubscriptionSplitRequestDTO": {
"required": [
"walletId"
],
"type": "object",
"properties": {
"walletId": {
"type": "string",
"description": "Asaas wallet identifier that will be transferred",
"nullable": false,
"deprecated": false,
"example": null
},
"fixedValue": {
"type": "number",
"description": "Fixed amount to be transferred to the account when the payment is received",
"deprecated": false,
"example": null
},
"percentualValue": {
"type": "number",
"description": "Percentage of the net value of the charge to be transferred when received",
"deprecated": false,
"example": null
},
"externalReference": {
"type": "string",
"description": "Split identifier in your system",
"deprecated": false,
"example": null
},
"description": {
"type": "string",
"description": "Split description",
"deprecated": false,
"example": null
}
},
"description": "Split information",
"deprecated": false
}
},
"securitySchemes": {
"Authorization": {
"type": "apiKey",
"name": "access_token",
"in": "header"
}
}
},
"x-readme": {
"headers": [
{
"key": "User-Agent",
"value": "NomeDaSuaAplicacao/1.0.0"
}
]
}
}
```
# Sibling pages
* [List subscriptions](https://docs.asaas.com/reference/list-subscriptions.md)
* [Create subscription with credit card](https://docs.asaas.com/reference/create-subscription-with-credit-card.md)
* [Retrieve a single subscription](https://docs.asaas.com/reference/retrieve-a-single-subscription.md)
* [Update existing subscription](https://docs.asaas.com/reference/update-existing-subscription.md)
* [Remove subscription](https://docs.asaas.com/reference/remove-subscription.md)
* [Update credit card without charging the subscription](https://docs.asaas.com/reference/update-subscription-credit-card.md)
* [List payments of a subscription](https://docs.asaas.com/reference/list-payments-of-a-subscription.md)
* [Generate subscription booklet](https://docs.asaas.com/reference/generate-subscription-booklet.md)
* [Create configuration for issuing invoices](https://docs.asaas.com/reference/create-configuration-for-issuance-of-invoices.md)
* [Retrieve configuration for issuing invoices](https://docs.asaas.com/reference/retrieve-configuration-for-issuance-of-invoices.md)
* [Remove configuration for issuing invoices](https://docs.asaas.com/reference/remove-configuration-for-issuance-of-invoices.md)
* [Update configuration for issuing invoices](https://docs.asaas.com/reference/update-configuration-for-issuance-of-invoices.md)
* [List invoices for subscription charges](https://docs.asaas.com/reference/list-invoices-for-subscription-charges.md)