> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # List coupons > This endpoint returns a list of all coupons for an account in a list format. The list of coupons is ordered starting from the most recently created coupon. The response also includes `pagination_metadata`, which lets the caller retrieve the next page of results if they exist. ## OpenAPI ````yaml /api-reference/orb-openapi.json get /coupons openapi: 3.1.0 info: title: API Reference description: >- Orb's API is built with the following principles in mind: 1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as cursor-based pagination and standardized error output. To help with debugging in critical API actions, the API always strives to provide detailed and actionable error messages. Aliases such as external customer IDs aid in fast integration times. 2. **Reliably real time**: Orb's event-based APIs, such as event ingestion are designed to handle extremely high throughput and scale with concurrent load. Orb also provides a real-time event-level credits ledger and a highly performant webhooks architecture. 3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage show the flexible nature of the platform. You can download the latest OpenAPI spec [here](https://api.withorb.com/spec.json) - pass `?version=3.0` for an OpenAPI 3.0-compatible spec. contact: name: Orb, Inc. url: https://www.withorb.com/ email: team@withorb.com version: '1.0' servers: - url: https://api.withorb.com/v1 description: Production server security: - APIKeyAuth: [] tags: - name: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. - name: Availability - name: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. - name: Credit description: >- The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid credits within Orb. - name: Credit note description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. - name: Customer description: >- A customer is a buyer of your products, and the other party to the billing relationship. In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an `external_customer_id` with your own identifier. See [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these aliases work in Orb. In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping. A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for information on what this timezone parameter influences within Orb. - name: Dimensional Price Group - name: Event description: >- The [Event](/core-concepts#event) resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period. - name: Invoice description: >- An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation. - name: Item description: >- The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes. - name: License - name: LicenseType description: >- The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key. - name: Metric description: >- The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers. - name: Plan description: >- The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the [Price resource](/reference/price). - name: Price description: >- The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill. Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price) - name: Price interval description: >- The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior. - name: Subscription description: >- A [subscription](/core-concepts#subscription) represents the purchase of a plan by a customer. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. Subscriptions also default to **beginning of month alignment**, which means the first invoice issued for the subscription will have pro-rated charges between the `start_date` and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing). Depending on the plan configuration, any _flat_ recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to **in-advance billing**. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period. - name: Subscription Change paths: /coupons: get: tags: - Coupon summary: List coupons description: >- This endpoint returns a list of all coupons for an account in a list format. The list of coupons is ordered starting from the most recently created coupon. The response also includes `pagination_metadata`, which lets the caller retrieve the next page of results if they exist. operationId: list-coupons parameters: - required: false style: form schema: type: integer maximum: 100 minimum: 1 title: Limit description: The number of items to fetch. Defaults to 20. default: 20 name: limit in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: Cursor description: >- Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request. name: cursor in: query - required: false style: form schema: oneOf: - type: boolean - type: 'null' title: Show Archived description: >- Show archived coupons as well (by default, this endpoint only returns active coupons). name: show_archived in: query - required: false style: form schema: oneOf: - type: string - type: 'null' title: Redemption Code description: Filter to coupons matching this redemption code. name: redemption_code in: query responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/Coupons' '400': description: Bad Request headers: {} content: application/json: schema: $ref: '#/components/schemas/400Error' '401': description: Unauthorized headers: {} content: application/json: schema: $ref: '#/components/schemas/401Error' '404': description: Not Found headers: {} content: application/json: schema: $ref: '#/components/schemas/404Error' '409': description: Conflict headers: {} content: application/json: schema: $ref: '#/components/schemas/409Error' '413': description: Content Too Large headers: {} content: application/json: schema: $ref: '#/components/schemas/413Error' '429': description: Too Many Requests headers: {} content: application/json: schema: $ref: '#/components/schemas/429Error' '500': description: Internal Server Error headers: {} content: application/json: schema: $ref: '#/components/schemas/500Error' components: schemas: Coupons: properties: data: items: $ref: '#/components/schemas/Coupon' type: array title: Data pagination_metadata: $ref: '#/components/schemas/PaginationMetadata' type: object required: - data - pagination_metadata title: Coupons 400Error: oneOf: - $ref: '#/components/schemas/ConstraintViolationError' - $ref: '#/components/schemas/DuplicateResourceCreationError' - $ref: '#/components/schemas/RequestValidationError' 401Error: $ref: '#/components/schemas/AuthorizationError' title: 401Error 404Error: oneOf: - $ref: '#/components/schemas/FeatureNotAvailableError' - $ref: '#/components/schemas/ResourceNotFoundError' - $ref: '#/components/schemas/URLNotFound' 409Error: $ref: '#/components/schemas/IdempotencyRequestMismatch' title: 409Error 413Error: oneOf: - $ref: '#/components/schemas/RequestTooLargeError' - $ref: '#/components/schemas/ResourceTooLargeError' - $ref: '#/components/schemas/TooManyResultsError' 429Error: $ref: '#/components/schemas/TooManyRequests' title: 429Error 500Error: $ref: '#/components/schemas/ServerError' title: 500Error Coupon: properties: id: type: string title: Id description: Also referred to as coupon_id in this documentation. examples: - 7iz2yanVjQoBZhyH redemption_code: type: string title: Redemption Code description: >- This string can be used to redeem this coupon for a given subscription. examples: - HALFOFF discount: $ref: '#/components/schemas/CouponDiscount' times_redeemed: type: integer title: Times Redeemed description: The number of times this coupon has been redeemed. duration_in_months: oneOf: - type: integer - type: 'null' title: Duration In Months description: >- This allows for a coupon's discount to apply for a limited time (determined in months); a `null` value here means "unlimited time". examples: - 12 max_redemptions: oneOf: - type: integer - type: 'null' title: Max Redemptions description: >- The maximum number of redemptions allowed for this coupon before it is exhausted; `null` here means "unlimited". archived_at: oneOf: - type: string format: date-time - type: 'null' title: Archived At description: >- An archived coupon can no longer be redeemed. Active coupons will have a value of null for `archived_at`; this field will be non-null for archived coupons. type: object required: - id - redemption_code - discount - times_redeemed - duration_in_months - max_redemptions - archived_at title: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. PaginationMetadata: properties: has_more: type: boolean title: Has More next_cursor: oneOf: - type: string - type: 'null' title: Next Cursor type: object required: - has_more - next_cursor title: PaginationMetadata ConstraintViolationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-constraint-violation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ConstraintViolationError DuplicateResourceCreationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: DuplicateResourceCreationError RequestValidationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-request-validation-errors title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title validation_errors: items: {} type: array title: Validation Errors type: object required: - type - status - validation_errors title: RequestValidationError AuthorizationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#401-authentication-error title: Type status: type: integer enum: - 401 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: AuthorizationError FeatureNotAvailableError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-feature-not-available title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: FeatureNotAvailableError ResourceNotFoundError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-resource-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: type: string title: Title type: object required: - type - status - title title: ResourceNotFoundError URLNotFound: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-url-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: URLNotFound IdempotencyRequestMismatch: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#409-resource-conflict title: Type status: type: integer enum: - 409 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: IdempotencyRequestMismatch RequestTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-request-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: RequestTooLargeError ResourceTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-resource-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ResourceTooLargeError TooManyResultsError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-too-many-results title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyResultsError TooManyRequests: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#429-too-many-requests title: Type status: type: integer enum: - 429 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyRequests ServerError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#500-internal-server-error title: Type status: type: integer title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ServerError CouponDiscount: oneOf: - $ref: '#/components/schemas/PercentageDiscount' - $ref: '#/components/schemas/AmountDiscount' discriminator: propertyName: discount_type mapping: amount: $ref: '#/components/schemas/AmountDiscount' percentage: $ref: '#/components/schemas/PercentageDiscount' PercentageDiscount: properties: discount_type: type: string enum: - percentage title: Discount Type applies_to_price_ids: oneOf: - items: type: string type: array - type: 'null' title: Applies To Price Ids description: >- List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices. examples: - - h74gfhdjvn7ujokd - 7hfgtgjnbvc3ujkl filters: oneOf: - items: $ref: '#/components/schemas/PriceFilter' type: array - type: 'null' title: Filters description: The filters that determine which prices to apply this discount to. reason: oneOf: - type: string - type: 'null' title: Reason percentage_discount: type: number maximum: 1 minimum: 0 title: Percentage Discount description: >- Only available if discount_type is `percentage`. This is a number between 0 and 1. examples: - 0.15 type: object required: - discount_type - percentage_discount title: PercentageDiscount AmountDiscount: properties: discount_type: type: string enum: - amount title: Discount Type applies_to_price_ids: oneOf: - items: type: string type: array - type: 'null' title: Applies To Price Ids description: >- List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices. examples: - - h74gfhdjvn7ujokd - 7hfgtgjnbvc3ujkl filters: oneOf: - items: $ref: '#/components/schemas/PriceFilter' type: array - type: 'null' title: Filters description: The filters that determine which prices to apply this discount to. reason: oneOf: - type: string - type: 'null' title: Reason amount_discount: type: string title: Amount Discount description: Only available if discount_type is `amount`. type: object required: - discount_type - amount_discount title: AmountDiscount PriceFilter: properties: field: type: string enum: - price_id - item_id - price_type - currency - pricing_unit_id title: Field description: The property of the price to filter on. operator: type: string enum: - includes - excludes title: Operator description: Should prices that match the filter be included or excluded. values: items: type: string type: array uniqueItems: true title: Values description: The IDs or values that match this filter. type: object required: - field - operator - values title: PriceFilter securitySchemes: APIKeyAuth: type: http description: API Keys can be issued in the Orb's web application. scheme: bearer ````