Sign in

v2

latestOpenAPI 3.0.0Commercial2026-07-2649110209.4 KB
Subscriptions

Update a subscription.

Modify subscription details like units, seats, or add-ons. Support proration and immediate billing options.

post/v1/subscriptions/{id}

Path parameters

idstring required

The unique identifier of the subscription

Request body

update_behavior'proration-charge-immediately' | 'proration-charge' | 'proration-none'

The update behavior for the subscription (defaults to proration)

Response

Successfully updated a subscription

idstring required

Unique identifier for the object.

mode'test' | 'prod' | 'sandbox' required

String representing the environment.

objectstring required

String representing the object's type. Objects of the same type share the same value.

collection_method'charge_automatically' required

The method used for collecting payments for the subscription.

status'active' | 'canceled' | 'unpaid' | 'paused' | 'trialing' | 'scheduled_cancel' | 'past_due' required

The current status of the subscription.

last_transaction_idstring

The ID of the last paid transaction.

last_transaction_datestring date-time

The date of the last paid transaction.

next_transaction_datestring date-time

The date when the next subscription transaction will be charged.

current_period_start_datestring date-time

The start date of the current subscription period.

current_period_end_datestring date-time

The end date of the current subscription period.

canceled_atstring date-time nullable

The date and time when the subscription was canceled, if applicable.

created_atstring date-time required

The date and time when the subscription was created.

updated_atstring date-time required

The date and time when the subscription was last updated.

metadataobject

Metadata for the subscription in the form of key-value pairs.

Example response

{
  "object": "subscription",
  "product": {
    "description": "This is a sample product description.",
    "image_url": "https://example.com/image.jpg",
    "image_urls": [
      "https://example.com/image.jpg"
    ],
    "features": [
      {
        "id": "feat_abc123",
        "description": "Access to premium course materials."
      }
    ],
    "price": 400,
    "currency": "USD",
    "product_url": "https://creem.io/product/prod_123123123123",
    "default_success_url": "https://example.com/?status=successful",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  "customer": {
    "email": "user@example.com",
    "name": "John Doe",
    "metadata": {
      "key": "value"
    },
    "country": "US",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  "last_transaction_id": "tran_3e6Z6TzvHKdsjEgXnGDEp0",
  "last_transaction": {
    "object": "transaction",
    "amount": 2000,
    "amount_paid": 2000,
    "discount_amount": 2000,
    "currency": "USD",
    "tax_country": "US",
    "tax_amount": 2000,
    "refunded_amount": 2000
  },
  "last_transaction_date": "2024-09-12T12:34:56Z",
  "next_transaction_date": "2024-09-12T12:34:56Z",
  "current_period_start_date": "2024-09-12T12:34:56Z",
  "current_period_end_date": "2024-09-12T12:34:56Z",
  "canceled_at": "2024-09-12T12:34:56Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-09-12T12:34:56Z",
  "discount": {
    "id": "dis_3e6Z6TzvHKdsjEgXnGDEp0",
    "discountCode": "HOLIDAY2024"
  },
  "metadata": {
    "userId": "user_123",
    "plan": "pro"
  }
}