---
title: "Create a new subscription"
method: POST
path: "/v1/subscriptions"
tags: ["Subscription"]
---

# Create a new subscription

`POST /v1/subscriptions`

## Request

- Base URL: `https://api.payretailers.com`
- URL: `https://api.payretailers.com/v1/subscriptions`
- Auth: HTTP basic

Creates a new subscription for recurring payments. Supports two authorization journeys: BACKGROUND (push notification) and USER_INTERACTION (QR code scan).

## Request body

- SubscriptionRequest
  - `subscriptionProductId` string, uuid, nullable: ID of a pre-configured subscription product. If provided, inherits product configuration.
  - `customer` CustomerRequest, required
    - `customerUniqueIdentifier` string, required: Unique customer identifier. Must exist in Customer Module.
    - `authorizationDetails` object, nullable: Bank account details required for BACKGROUND authorization type.
  - `channel` string, required: Payment channel/method. Valid values: PIX (PIX Automatic), WALLET (coming soon), SPEI (coming soon).
  - `authorizationType` string, required: Authorization type. Valid values: BACKGROUND (Journey 1 - push notification, requires authorizationDetails), USER_INTERACTION (Journey 2 - QR code scan). INITIAL_PAYMENT (Journey 3 - Subscription and a First Immediate Payment)
  - `frequency` string, required: Payment frequency. Valid values: WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL.
  - `retryPolicy` RetryPolicy, required
    - `type` string, required: Retry policy type. Valid values: PIX_SPECIFIC (auto-configured for PIX), FIXED_RETRY (requires maxRetries and retryIntervalDays), NOT_ALLOWED (no retries).
    - `maxRetries` integer, nullable: Maximum number of retry attempts. Required when type is FIXED_RETRY.
    - `retryIntervalDays` integer, nullable: Days between retry attempts. Required when type is FIXED_RETRY.
  - `initialPayment` InitialPaymentModel
    - `description` string, nullable: Initial payment description.
    - `amount` integer, required: Amount in cents. Required.
    - `expiration` integer, nullable: Expiration time for the initial payment in seconds, defaults to 86400.
  - `startDate` string, date-time, nullable: Subscription start date in ISO 8601 format
  - `expirationDate` string, date-time, nullable: Subscription expiration date in ISO 8601 format
  - `authorizationExpirationTime` integer, nullable: Optional. Time window in minutes the customer has to authorize the mandate before the subscription is transitioned to EXPIRED. If omitted, defaults to 2880 minutes (48 hours). The value is persisted on the subscription and propagated to the PSP integration so the deadline is enforced end-to-end.
  - `amount` AmountModel, required
    - `type` string, nullable: Amount type. Valid values: FIXED (requires fixedValue), VARIABLE (requires minValue and maxValue).
    - `fixedValue` integer, nullable: Fixed payment amount in cents. Required when type is FIXED.
    - `minValue` integer, nullable: Minimum payment amount in cents. Required when type is VARIABLE.
    - `maxValue` integer, nullable: Maximum payment amount in cents. Required when type is VARIABLE.
    - `currency` string, required: ISO currency code (3 characters)
  - `notificationUrl` string, uri, required: Webhook URL for receiving subscription and payment events. Must be HTTPS.
  - `country` string, required: ISO country code (2 characters)
  - `automaticScheduleAllowed` boolean: Whether payments should be automatically scheduled
  - `description` string, nullable: Description of the subscription
  - `language` string, required: ISO language code (2 characters)
  - `internalReferenceId` string, required: Your internal reference ID for this subscription. Required — used for correlation across webhooks, reporting and reconciliation. Max length: 50 characters.
  - `metadata` object, nullable: Custom metadata key-value pairs

## Response `201`

Subscription created successfully

- SubscriptionCreationResponse
  - `subscriptionId` string, uuid: Unique identifier for the created subscription
  - `subscriptionPaymentId` string, uuid: Unique identifier for the created initial payment/transaction, this ID corresponds with the transaction ID
  - `status` string: Initial subscription status
  - `checkout` CheckoutModel
    - `checkoutUrl` string, uri, nullable: URL to display QR code (coming soon)
    - `payload` PayloadModel
      - `code` string, nullable: EMV code for 'copia e cola' (copy and paste). Present for USER_INTERACTION authorization.
      - `image` string, nullable: QR code image in base64 format (data URI). Present for USER_INTERACTION authorization.

## Other responses

- `400`: Bad Request - Validation error

---

[API](https://skmtc.dev/payretailers/apis/subscriptions-module-api.md) - [All operations](https://skmtc.dev/payretailers/apis/subscriptions-module-api/llms.txt) - [OpenAPI document](https://skmtc.dev/payretailers/apis/subscriptions-module-api/revisions/dd2464c871f8?raw)