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

# Create a new subscription

`POST /v1/subscriptions`

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
  - `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, nullable — Your internal reference ID for this subscription
  - `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.net/payretailers/apis/transaction.md) · [All operations](https://skmtc.net/payretailers/apis/transaction/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payretailers/transaction/revisions/b022ee3a593d/schema)