CRcreem
Subscriptions

Upgrade a subscription to a different product

Changed on

Upgrade a subscription to a different product or plan. Handle proration and plan changes seamlessly.

post/v1/subscriptions/{id}/upgrade

Request

Path parameters

idstring required

The unique identifier of the subscription

Request body

product_idstring required

The ID of the product to upgrade to

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

The update behavior for the subscription (defaults to proration-charge-immediately)

Example request

{
  "product_id": "prod_123"
}

Response

Successfully upgraded the 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.",
        "customer_credits": {
          "amount": "100",
          "unit_label": "tokens",
          "bucket_name": "images"
        }
      }
    ],
    "usage_prices": [
      {
        "id": "price_abc123",
        "meter_id": "mtr_abc123",
        "unit_price": 0.002,
        "free_allowance": 1000,
        "cap": 50000,
        "target_account_name": "images"
      }
    ],
    "price": 400,
    "currency": "USD",
    "recurring_interval": "month",
    "recurring_interval_count": 3,
    "trial_period_days": 7,
    "trial_price": 100,
    "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",
    "external_id": "user-42",
    "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"
  }
}

Changes

  • e194a0be46dcRevision changes
    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

  • ab9722a7eb0cRevision changes
    • breaking

      the ///// response's property type changed from object to string for status