---
title: "Update a price"
method: PATCH
path: "/subscriptions/{subscription_id}/price"
tags: ["Subscriptions"]
---

# Update a price

`PATCH /subscriptions/{subscription_id}/price`

Updates the recurring `amount` of the price attached to a subscription. Each subscription owns its own price. The new amount is picked up automatically by the next draft bill. The subscription must be in 'incomplete', 'active', or 'trialing' status, and the price must be a flat (`fixed`) price — updating instalment (tiered) prices is not yet supported.

## Path parameters

- `subscription_id` string, required

## Query parameters

- `expand` string

## Request body

- UpdatePriceRequest
  - `amount` number, required — The new recurring amount in major currency units. Must be greater than or equal to zero and respect the decimal places allowed for the price's currency.

## Response `200`

Price Updated

- Subscription
  - `id` string, 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.
  - `customer` object, required — The customer associated with this subscription.
    - `customer_id` string, uuid, required — Unique ID assigned by Acquired to the customer.
  - `payment_methods` SubscriptionPaymentMethod[], nullable
    - `type` string, required — The kind of payment method, e.g. `card`.
    - `payment_method_id` string, required — Unique ID associated to a payment method within Acquired system, e.g.: card ID.
    - `is_primary` boolean, required — Whether this is the primary payment method used to bill the subscription. Exactly one payment method must be marked primary.
    - `transaction_id` string, uuid, nullable — Transaction ID from a previous payment. If provided on the primary payment method during creation, the first bill is marked as prepaid.
  - `product` union — The product associated with the subscription. **Expandable**: By default, this returns an object with only the `product_id`. Use the `expand` query parameter to include the full product object.
    - ProductRef — A reference to a product, containing only the product ID.
      - `product_id` string, required — Unique ID assigned by Acquired to the product.
    - ProductBase
      - `product_id` string, required — Unique ID assigned by Acquired to the product.
      - `name` string, required — Display name for the product.
      - `description` string, required — Longer-form description of the product.
      - `created_at` string, date-time, required — When the product was created.
  - `price` union — The price associated with the subscription. **Expandable**: By default, this returns an object with only the `price_id`. Use the `expand` query parameter to include the full price object.
    - PriceRef — A reference to a price, containing only the price ID.
      - `price_id` string, required — Unique ID assigned by Acquired to the price.
    - PriceBase
      - `price_id` string, required — Unique ID assigned by Acquired to the price.
      - `product_id` string, required — ID of the product this price belongs to.
      - `usage_type` 'fixed' | 'instalment', required — - `fixed`: Standard recurring billing. `amount` is required. - `instalment`: Instalment pricing for complex billing (e.g., Loans). `cycles` is required.
      - `amount` number, nullable — The recurring amount in major currency units for 'fixed' prices. Null if 'instalment'.
      - `cycles` PriceCycle[], nullable — A list of specific amounts per cycle. Required if usage_type is 'instalment'.
        - `cycle` integer, required — The specific cycle sequence number (0-indexed). 0 represents the first bill.
        - `amount` number, required — The amount to bill for this specific cycle in major currency units.
      - `cycle_details` PriceCycleDetails, required — Details regarding the frequency and duration of the billing cycles.
        - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time for the billing cycle.
        - `interval_count` integer, required — The number of intervals between billing cycles.
        - `limit` integer, nullable — Total number of billing cycles before the subscription ends.
      - `currency` 'GBP' | 'USD' | 'EUR', required — The currency this price is denominated in.
      - `created_at` string, date-time, required — When the price was created.
  - `discount` union — The discount applied to the subscription, if any. **Expandable**: By default, this returns an object with only the `coupon_id`. Use the `expand` query parameter to include the full discount object.
    - DiscountRef — A reference to a discount, containing only the coupon ID.
      - `coupon_id` string, required — ID of the coupon that defines this discount.
    - DiscountBase
      - `coupon_id` string, required — ID of the coupon that defines this discount.
      - `discount_type` 'percentage' | 'fixed_amount', required — Whether the discount applies a `percentage` or `fixed_amount` reduction.
      - `value` number, required — The discount value. For percentage: 20 = 20%. For fixed_amount: 5.00 = 5.00 in the subscription currency.
      - `remaining_cycles` integer, nullable — Number of remaining billing cycles the discount applies to. Null for 'forever' duration.
      - `applied_at` string, date-time, required — When the discount was applied to the subscription.
      - `effective_from` string, date-time, required — When the discount becomes active. Can be in the future for scheduled activation.
      - `end_date` string, date-time, nullable — When the discount expires.
  - `start_date` string, date-time, nullable — When the subscription was first activated. Null while the subscription is incomplete.
  - `trial_end` string, date-time, nullable — If set, the subscription is in 'trialing' status until this date.
  - `cancel_at_period_end` boolean, required — True when the subscription is scheduled to cancel when the next bill becomes due.
  - `transaction` object, nullable — Custom transaction data associated with the subscription.
    - `custom_data` string, nullable — Custom data. Base64 encoded string.
    - `custom1` string, nullable — Custom field 1.
    - `custom2` string, nullable — Custom field 2.
  - `payment` object, nullable — Payment configuration for the subscription.
    - `reference` string, nullable — Merchant payment reference. Passed to the payment gateway on each recurring payment attempt.
  - `payment_failure_configuration` object, required — The subscription's configuration for handling failed bill payments. Always present in the response; `recovery_strategy` is `none` when the subscription is not enrolled.
    - `recovery_strategy` string — The name of the recovery strategy the subscription is enrolled in. Returns `none` when the subscription is not enrolled in automated payment recovery.
    - `incomplete_bills_before_cancellation` integer, nullable — The number of consecutive unpaid bills after which the subscription is automatically cancelled. Null when auto-cancellation is not configured.
  - `webhook_url` string, nullable — URL for receiving status update callbacks when bill payment status changes.
  - `created_at` string, date-time, required — When the subscription record was created.
  - `links` object[], required
    - `rel` 'self' | 'customer'
    - `href` string — Link to the resource which should be appended to base URL.
    - `method` string — The HTTP method to use with the link.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.dev/acquired/apis/acquired-api.md) · [All operations](https://skmtc.dev/acquired/apis/acquired-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/acquired/acquired-api/revisions/7ae178a046f2/schema)