Create a subscription
Create a subscription **Catalog-only (Selectwin-strict):** the price/billing model comes from the product variant, never the request — the variant must have `pricingType=recurring` (else `422`). Metered/tiered subscriptions use the same request shape; the behavior is driven by the variant. A `freeTrial` subscription is born `trialing` and is NOT charged until the trial ends.
Create a subscription
Catalog-only (Selectwin-strict): the price/billing model comes from the product variant, never the request — the variant must have pricingType=recurring (else 422). Metered/tiered subscriptions use the same request shape; the behavior is driven by the variant. A freeTrial subscription is born trialing and is NOT charged until the trial ends.
API key para requisições autenticadas. Envie sua chave no cabeçalho selectkey (sandbox sk_test_…, produção sk_live_…).
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "customer": { "id": "cus_0a1b2c3d4e5f60718293" }, "items": [ { "variantId": "var_0a1b2c3d4e5f60718293", "quantity": 1 } ], "payment": { "method": "credit", "card": { "id": "card_0a1b2c3d4e5f60718293" }, "installments": 1 } }'{
"id": "subs_0a1b2c3d4e5f60718293",
"status": "trialing",
"currency": "BRL",
"method": "credit",
"type": "recurring",
"currentCycle": {
"id": "scy_0a1b2c3d4e5f60718293",
"cycle": 1,
"status": "scheduled",
"startDate": "2026-01-15T12:00:00.000Z",
"endDate": null,
"dueDate": "2026-01-22T12:00:00.000Z",
"billedAt": null,
"updatedAt": "2026-01-15T12:00:00.000Z",
"createdAt": "2026-01-15T12:00:00.000Z"
},
"customer": {
"id": "cus_0a1b2c3d4e5f60718293",
"firstName": "Maria",
"lastName": "Silva",
"email": "[email protected]",
"birthdate": null,
"gender": null,
"document": {
"type": "cpf",
"number": "12345678900"
},
"telephone": {
"countryCode": "55",
"areaCode": "11",
"number": "999999999",
"line": "+5511999999999"
},
"available": true,
"delinquent": false,
"externalReference": null,
"additionalEmails": null,
"metadata": null,
"updatedAt": "2026-01-15T12:00:00.000Z",
"createdAt": "2026-01-15T12:00:00.000Z"
},
"billing": {
"frequency": "monthly",
"frequencyCount": 1,
"endDate": null,
"exactDay": null,
"freeTrialDays": 7,
"address": {
"street": null,
"number": null,
"complement": null,
"district": null,
"city": null,
"state": null,
"country": null,
"postcode": null,
"line": null,
"fingerprint": null,
"line1": null,
"line2": null,
"line3": null
}
},
"discount": null,
"discounts": null,
"shippable": false,
"shipping": null,
"spplited": false,
"splits": null,
"items": [
{
"id": "sit_0a1b2c3d4e5f60718293",
"name": "Plano Pro",
"description": null,
"enabled": true,
"pricingSchema": "unit",
"unitPrice": 4990,
"quantity": 1,
"currency": "BRL",
"images": null,
"metadata": null,
"externalReference": null,
"updatedAt": "2026-01-15T12:00:00.000Z",
"createdAt": "2026-01-15T12:00:00.000Z"
}
],
"callback": null,
"geolocation": null,
"externalReference": null,
"metadata": null,
"updatedAt": "2026-01-15T12:00:00.000Z",
"createdAt": "2026-01-15T12:00:00.000Z",
"merchant": {
"name": "Acme Ltda",
"merchantId": "bus_0a1b2c3d4e5f60718293",
"isSubAccount": false
},
"_links": {
"self": {
"href": "https://api.selectwin.io/v1/subscriptions/subs_…",
"method": "GET"
}
}
}{
"error": {
"status": "Bad Request",
"statusCode": 400,
"category": "validation",
"code": "invalidParameters",
"message": "Validation errors occurred.",
"resource": "server"
}
}{
"error": {
"status": "Unauthorized",
"statusCode": 401,
"category": "authentication",
"code": "unauthorized",
"message": "Authentication is required to access this resource.",
"resource": "server"
}
}{
"error": {
"status": "Forbidden",
"statusCode": 403,
"category": "authorization",
"code": "forbidden",
"message": "You do not have permission to perform this action.",
"resource": "server"
}
}{
"error": {
"status": "Internal Server Error",
"statusCode": 500,
"category": "server",
"code": "notFound",
"message": "An unexpected error occurred.",
"resource": "server"
}
}{
"error": {
"status": "Conflict",
"statusCode": 409,
"category": "client",
"code": "idempotencyInProgress",
"message": "A request with this idempotency key is already being processed.",
"resource": "server"
}
}{
"error": {
"status": "Bad Request",
"statusCode": 400,
"category": "validation",
"code": "invalidParameters",
"message": "Validation errors occurred.",
"resource": "server"
}
}{
"error": {
"status": "Internal Server Error",
"statusCode": 500,
"category": "server",
"code": "serverError",
"message": "An unexpected error occurred. Please try again later.",
"resource": "server",
"details": "If the problem persists, contact support with the correlationId from the response headers."
}
}