Sign in

v1

latestOpenAPI 3.0.32026-07-248079274.0 KB
Subscriptions

Apply a discount

Applies a coupon to a subscription, creating a discount. Only one discount can be active per subscription at a time. The subscription must be in 'active' or 'trialing' status.

post/subscriptions/{subscription_id}/discount

Path parameters

subscription_idstring required
Example:01HNY4G8G5ZMAXQB8T0Z1Y1ZMW

Unique identifier for the subscription.

Query parameters

expandstring
Example:product,price,discount

Comma-separated list of fields to expand in the response. Fields marked as Expandable in the response schema can be expanded. Supported fields: product, price, discount.

Request body

coupon_idstring required

The ID of the coupon to apply.

effective_fromstring date-time nullable

When the discount should become active. If omitted, the discount is effective immediately. If provided, must not be in the past.

Example request

{
  "coupon_id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV"
}

Response

Discount Applied

idstring required

Unique ID assigned by Acquired to the subscription when it is created.

status'trialing' | 'active' | 'incomplete' | 'paused' | 'cancelled' | 'past_due' required

Current lifecycle status of the subscription.

start_datestring date-time nullable

When the subscription was first activated. Null while the subscription is incomplete.

trial_endstring date-time nullable

If set, the subscription is in 'trialing' status until this date.

cancel_at_period_endboolean required

True when the subscription is scheduled to cancel when the next bill becomes due.

webhook_urlstring nullable

URL for receiving status update callbacks when bill payment status changes.

created_atstring date-time required

When the subscription record was created.

Example response

{
  "id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
  "status": "active",
  "customer": {
    "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240"
  },
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "266761e2-de8b-44df-b7e3-7ab42421bce8",
      "is_primary": true
    }
  ],
  "product": {
    "product_id": "01HNY4G8G06M4J4J9P11CR3BCG"
  },
  "price": {
    "price_id": "01HNY4G8G2WJ6S7G8R9QAF3KZY"
  },
  "discount": {
    "coupon_id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV"
  },
  "start_date": "2025-11-01T09:00:00Z",
  "trial_end": "2025-11-15T09:00:00Z",
  "payment": {
    "reference": "ORDER-12345"
  },
  "payment_failure_configuration": {
    "recovery_strategy": "example_strategy",
    "incomplete_bills_before_cancellation": 3
  },
  "webhook_url": "https://example.com/webhooks/billing",
  "links": [
    {
      "rel": "self",
      "href": "/v1/subscriptions/01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
      "method": "GET"
    }
  ]
}