Guides
Support
Start typing to search…

Subscription Products

Subscription Products

What are Subscription Products?

Subscription Products are reusable templates that define common subscription parameters. Instead of specifying all parameters each time you create a subscription, you can create a product once and reuse it across multiple subscriptions.

Products help maintain consistency, simplify subscription creation, and enable centralized management of subscription plans.

When to Use Products

Recommended When

  • You have multiple subscriptions with the same configuration
  • You want to maintain consistency in pricing and policies
  • You need to easily update plans across multiple subscriptions
  • You want to activate/deactivate plans without affecting existing subscriptions

Optional When

  • You have unique subscriptions with different configurations
  • You prefer to specify all parameters in each subscription
  • You're testing or prototyping

Product Configuration

Required Fields

  • channel: Payment method (PIX, WALLET, etc.)
  • frequency: Payment frequency (WEEKLY, MONTHLY, QUARTERLY, etc.)
  • amount: Amount configuration (FIXED or VARIABLE)
  • retryPolicy: Retry policy configuration
  • authorizationType: BACKGROUND or USER_INTERACTION
  • country: Country code (e.g., "BR")
  • language: Language code (e.g., "PT", "EN")
  • notificationUrl: Webhook URL for notifications

Optional Fields

  • description: Description of the product
  • startDate: Default start date
  • expirationDate: Default expiration date
  • automaticScheduleAllowed: Whether automatic scheduling is enabled (default: false)
  • integrationCode: Override default integration code
  • paymentMethodTag: Override default payment method tag
  • internalReferenceId: Merchant reference ID
  • metadata: Key-value metadata dictionary

Creating a Product

Request Example

POST /v1/subscription-products
{
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "automaticScheduleAllowed": true,
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt",
  "description": "Monthly subscription plan"
}

Response

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000"
}

Using a Product in Subscriptions

Create Subscription with Product

When creating a subscription, you can reference a product using subscriptionProductId. The subscription will inherit all configuration from the product, but you can override specific fields if needed.

Request Example:

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "customerUniqueIdentifier": "customer-123"
  },
  "startDate": "2025-02-01T00:00:00Z",
  "expirationDate": "2025-12-31T23:59:59Z"
}

Benefits:

  • Simpler subscription creation
  • Consistent configuration
  • Easy to update multiple subscriptions by updating the product

Override Product Fields

You can override specific fields from the product when creating a subscription:

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "customerUniqueIdentifier": "customer-123"
  },
  "amount": {
    "type": "FIXED",
    "fixedValue": 15000,
    "currency": "BRL"
  },
  "startDate": "2025-02-01T00:00:00Z"
}

In this example, the subscription uses the product's configuration but overrides the amount.

Managing Products

Get Product by ID

GET /v1/subscription-products/{id}

Response:

{
  "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "automaticScheduleAllowed": true,
  "country": "BR",
  "language": "pt",
  "description": "Monthly subscription plan",
  "isActive": true
}

Get Products by Filters

GET /v1/subscription-products?shopId={shopId}&country={country}&channel={channel}

Query Parameters:

  • shopId: Filter by shop ID
  • country: Filter by country code
  • channel: Filter by payment channel

Response:

[
  {
    "subscriptionProductId": "550e8400-e29b-41d4-a716-446655440000",
    "channel": "PIX",
    "frequency": "MONTHLY",
    "amount": {
      "type": "FIXED",
      "fixedValue": 10000,
      "currency": "BRL"
    },
    "isActive": true
  },
  {
    "subscriptionProductId": "660e8400-e29b-41d4-a716-446655440001",
    "channel": "PIX",
    "frequency": "QUARTERLY",
    "amount": {
      "type": "FIXED",
      "fixedValue": 25000,
      "currency": "BRL"
    },
    "isActive": true
  }
]

Update Product

PUT /v1/subscription-products/{id}

Request Example:

{
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 12000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "automaticScheduleAllowed": true,
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt",
  "description": "Updated monthly subscription plan"
}

Note: Updating a product does not affect existing subscriptions that were created using the product. Only new subscriptions will use the updated configuration.

Activate Product

POST /v1/subscription-products/{id}/activate

Activates a product, making it available for use in new subscriptions.

Deactivate Product

POST /v1/subscription-products/{id}/deactivate

Deactivates a product. Deactivated products:

  • Cannot be used in new subscriptions
  • Do not affect existing subscriptions created with the product
  • Can be reactivated later

Product Lifecycle

Active Products

  • Can be used in new subscriptions
  • Appear in product listings
  • Can be updated

Inactive Products

  • Cannot be used in new subscriptions
  • Do not appear in product listings (unless explicitly requested)
  • Existing subscriptions are not affected
  • Can be reactivated

Benefits of Using Products

Consistency

All subscriptions created from the same product have identical configuration, ensuring consistent pricing, policies, and behavior.

Centralized Management

Update a product once to affect all future subscriptions. This simplifies plan management and reduces errors.

Easy Updates

Change pricing, retry policies, or other settings in one place. New subscriptions automatically use the updated configuration.

Activation/Deactivation

Easily enable or disable plans without affecting existing subscriptions. This is useful for:

  • Seasonal plans
  • Promotional offers
  • Plan deprecation

Best Practices

Organize by Use Case

Create products for different use cases:

  • Monthly plans
  • Annual plans
  • Trial periods
  • Different pricing tiers

Use Descriptive Names

Include clear descriptions to identify product purpose:

{
  "description": "Monthly Premium Plan - PIX Automatic"
}

Version Control

When making significant changes, consider creating a new product instead of updating an existing one. This allows you to:

  • Maintain historical data
  • Support multiple plan versions
  • Gradual migration

Test Before Activating

Test product configuration thoroughly before activating, especially:

  • Retry policies
  • Amount configurations
  • Automatic scheduling settings

Example: Complete Product Workflow

Step 1: Create Product

POST /v1/subscription-products
{
  "channel": "PIX",
  "frequency": "MONTHLY",
  "amount": {
    "type": "FIXED",
    "fixedValue": 10000,
    "currency": "BRL"
  },
  "retryPolicy": {
    "type": "PIX_SPECIFIC"
  },
  "authorizationType": "BACKGROUND",
  "automaticScheduleAllowed": true,
  "notificationUrl": "https://your-domain.com/webhooks/subscriptions",
  "country": "BR",
  "language": "pt",
  "description": "Monthly subscription plan"
}

Response: subscriptionProductId: "product-123"

Step 2: Create Multiple Subscriptions

# Subscription 1
POST /v1/subscriptions
{
  "subscriptionProductId": "product-123",
  "customer": { "customerUniqueIdentifier": "customer-1" },
  "startDate": "2025-02-01T00:00:00Z"
}

# Subscription 2
POST /v1/subscriptions
{
  "subscriptionProductId": "product-123",
  "customer": { "customerUniqueIdentifier": "customer-2" },
  "startDate": "2025-02-01T00:00:00Z"
}

Step 3: Update Product (Optional)

PUT /v1/subscription-products/product-123
{
  "amount": {
    "type": "FIXED",
    "fixedValue": 12000,
    "currency": "BRL"
  },
  ...
}

Note: Existing subscriptions are not affected. Only new subscriptions will use the updated price.

Step 4: Deactivate Product (When Needed)

POST /v1/subscription-products/product-123/deactivate

Existing subscriptions continue to work. New subscriptions cannot use this product.

Next Steps

Updated about 8 hours ago