openapi: 3.0.3
info:
title: Quickstart API Reference
version: '2025-04-16'
description: >+
To use the Quickstart API, you must have the following features enabled on
your tenant:
* [Orders](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders)
or [Orders
Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization)
* [Invoice
Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement)
To find the latest changes made to the Zuora Quickstart API, check the
[Quickstart API
Changelog](https://developer.zuora.com/quickstart-api/changelog/2022q4-changelog/).
We recommend that you subscribe to [Developers
Community](https://community.zuora.com/communities/community-home?communitykey=e2a932b4-50c4-4019-a3e8-362e38714df3)
to get notifications when a new version is released.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
parameters:
zuora-track-id:
in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value for
this header, Zuora returns the same value in the response header. This
header enables you to track your API calls to assist with
troubleshooting in the event of an issue. The value of this field must
use the US-ASCII character set and must not include any of the following
characters: colon (:), semicolon (;), double quote ("), or quote (').
schema:
type: string
zuora-entity-ids:
in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have Multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the authorization
token is only valid for a single entity or you do not have Multi-entity
enabled, you do not need to set this header.
schema:
type: string
idempotency-key:
in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an idempotent
POST or PATCH request. Do not use this header in other request types.
This idempotency key should be a unique value, and the Zuora server
identifies subsequent retries of the same request using this value. For
more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
accept-encoding:
in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses, which
can reduce the bandwidth required for a response. If specified, Zuora
automatically compresses responses that contain over 1000 bytes. For
more information about this header, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
content-encoding:
in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request. Upload
a gzipped file for the payload if you specify this header. For more
information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
async:
in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications more
efficiently by leveraging Zuora's infrastructure to enqueue and execute
requests for you without blocking. These requests also use built-in
retry semantics, which makes them much less likely to fail for
non-deterministic reasons, even in extreme high-throughput scenarios.
Meanwhile, when you send a request to one of these endpoints, you can
expect to receive a response in less than 150 milliseconds and these
calls are unlikely to trigger rate limit errors. If set to true, Zuora
returns a 202 Accepted response, and the response body contains only a
request ID.
schema:
type: boolean
default: false
schemas:
customFields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_object:
type: object
title: Custom_object
description: The custom object data.
additionalProperties: true
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
readOnly: true
description: Custom Object Definition Type.
customObjectCreateRequest:
type: object
title: CustomObjectCreateRequest
description: ''
additionalProperties: true
example:
fieldName__c: sample Value
customObjectPatchRequest:
type: object
title: CustomObjectPatchRequest
description: ''
additionalProperties: true
listCustomObjectResponse:
type: object
title: ListCustomObjectResponse
description: A list of custom objects.
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/custom_object'
address:
type: object
title: Address
description: Container for the address informtion.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: Address line 2 (e.g., apartment, suite, unit, or building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
state:
type: string
description: State or providence
example: GA
country:
type: string
description: The country of the contact's address.
example: United States
county:
type: string
description: Zuora Tax uses this information to calculate county taxation.
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
money:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
queryRun:
type: object
title: QueryRun
description: Query run information.
additionalProperties: false
properties:
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object.
id:
type: string
readOnly: true
description: Unique identifier for the object.
sql:
type: string
description: The SQL statement of the query.
remaining_attempts:
type: number
description: >-
The remaining number of times Zuora will attempt the query before
terminating the query and setting the state to `failed`.
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO-8601 UTC
format.
file:
type: object
title: QueryRunFile
description: The file object representing the results of the query.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
url:
type: string
description: The URL from which the file can be downloaded
content_type:
type: string
enum:
- json
- jsonl
- csv
- tsv
- dsv
description: The type of the file returned.
type:
type: string
enum:
- query_run
description: The type of file.
number_of_rows:
type: number
description: The number of rows in the output file.
processing_duration:
type: number
description: The time taken to process the query in milliseconds.
state:
type: string
enum:
- pending
- accepted
- in_progress
- complete
- failed
- canceled
description: >-
The query's execution state, which will be completed for successful
runs.
column_separator:
type: string
description: >-
The character used as delimiter to separate values in the output
file.
This field is only applicable when `content_type` is `dsv`.
queryRunCreateRequest:
type: object
title: QueryRunCreateRequest
description: ''
additionalProperties: false
properties:
column_separator:
type: string
description: >-
The character used as delimiter to separate values in the output
file.
This field is only applicable when `content_type` is `dsv`.
content_encoding:
type: string
enum:
- gzip
- zip
- none
description: >-
If supplied, Zuora with compress the output file using the specified
compression algorithm.
encryption_key:
type: string
description: >-
Base64-encoded public key of a 1024-bit RSA key-pair. If you set
this field, Zuora will encrypt the query results using the provided
public key. You must use the corresponding private key to decrypt
the query results.
content_type:
type: string
enum:
- json
- csv
- tsv
- dsv
description: The type of the file returned.
sql:
type: string
description: The SQL statement of the query.
read_deleted:
type: boolean
description: If set to `true`, any deleted records are included in the response.
required:
- sql
- content_type
contact:
type: object
title: Contact
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
address:
type: object
title: Address
description: Container for the address informtion.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: Address line 2 (e.g., apartment, suite, unit, or building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
state:
type: string
description: State or providence
example: GA
country:
type: string
description: The country of the contact's address.
example: United States
county:
type: string
description: Zuora Tax uses this information to calculate county taxation.
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
first_name:
type: string
description: Customer first name.
example: Amy
home_phone:
type: string
description: Customer home phone (including extension).
example: (888)976-9056
last_name:
type: string
description: Customer last name.
example: Lawrence
mobile_phone:
type: string
description: Customer phone (including extension).
example: (888)101-0011
nickname:
type: string
description: Nickname for this contact.
example: Ami
other_phone:
type: string
description: Other customer phone (including extension).
example: (888)100-0001
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
tax_region:
type: string
description: A region defined in your Zuora Tax rules.
example: Georgia
work_email:
type: string
description: Customer work email.
example: alawrence@zuora.com
work_phone:
type: string
description: Customer work phone.
example: (888)976-9056
other_phone_type:
type: string
enum:
- work
- mobile
- home
- other
description: The type of the additional phone number.
fax:
type: string
description: The contact's fax number.
account_id:
type: string
description: >-
Identifier of a customer account with which this contact is
associated.
example: 2c92c0f86a8dd422016a9e7a70116b0d
contactPatchRequest:
type: object
title: ContactPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
address:
$ref: '#/components/schemas/address'
first_name:
type: string
description: Customer first name.
example: Amy
home_phone:
type: string
description: Customer home phone (including extension).
example: (888)976-9056
last_name:
type: string
description: Customer last name.
example: Lawrence
mobile_phone:
type: string
description: Customer phone (including extension).
example: (888)101-0011
nickname:
type: string
description: Nickname for this contact.
example: Ami
other_phone:
type: string
description: Other customer phone (including extension).
example: (888)100-0001
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
tax_region:
type: string
description: A region defined in your Zuora Tax rules.
example: Georgia
work_email:
type: string
description: Customer work email.
example: alawrence@zuora.com
work_phone:
type: string
description: Customer work phone.
example: (888)976-9056
other_phone_type:
type: string
enum:
- work
- mobile
- home
- other
description: The type of the additional phone number.
fax:
type: string
description: The contact's fax number.
account_id:
type: string
description: >-
Identifier of a customer account with which this contact is
associated.
example: 2c92c0f86a8dd422016a9e7a70116b0d
contactCreateRequest:
type: object
title: ContactCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
address:
$ref: '#/components/schemas/address'
first_name:
type: string
description: Customer first name.
example: Amy
home_phone:
type: string
description: Customer home phone (including extension).
example: (888)976-9056
last_name:
type: string
description: Customer last name.
example: Lawrence
mobile_phone:
type: string
description: Customer phone (including extension).
example: (888)101-0011
nickname:
type: string
description: Nickname for this contact.
example: Ami
other_phone:
type: string
description: Other customer phone (including extension).
example: (888)100-0001
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
tax_region:
type: string
description: A region defined in your Zuora Tax rules.
example: Georgia
work_email:
type: string
description: Customer work email.
example: alawrence@zuora.com
work_phone:
type: string
description: Customer work phone.
example: (888)976-9056
other_phone_type:
type: string
enum:
- work
- mobile
- home
- other
description: The type of the additional phone number.
fax:
type: string
description: The contact's fax number.
account_id:
type: string
description: >-
Identifier of a customer account with which this contact is
associated. Either `account_id` or `account_number` is required.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account_number:
type: string
description: >-
Human-readable identifier of the account with which this contact is
associated. Either `account_number` or `account_id` is required.
example: RC-00020831
required:
- first_name
- last_name
accountContactCreateRequest:
type: object
title: AccountContactCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
address:
$ref: '#/components/schemas/address'
first_name:
type: string
description: Customer first name.
example: Amy
home_phone:
type: string
description: Customer home phone (including extension).
example: (888)976-9056
last_name:
type: string
description: Customer last name.
example: Lawrence
mobile_phone:
type: string
description: Customer phone (including extension).
example: (888)101-0011
nickname:
type: string
description: Nickname for this contact.
example: Ami
other_phone:
type: string
description: Other customer phone (including extension).
example: (888)100-0001
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
tax_region:
type: string
description: A region defined in your Zuora Tax rules.
example: Georgia
work_email:
type: string
description: Customer work email.
example: alawrence@zuora.com
work_phone:
type: string
description: Customer work phone.
example: (888)976-9056
other_phone_type:
type: string
enum:
- work
- mobile
- home
- other
description: The type of the additional phone number.
fax:
type: string
description: The contact's fax number.
required:
- first_name
- last_name
accountContactPatchRequest:
type: object
title: AccountContactPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
address:
$ref: '#/components/schemas/address'
first_name:
type: string
description: Customer first name.
example: Amy
home_phone:
type: string
description: Customer home phone (including extension).
example: (888)976-9056
last_name:
type: string
description: Customer last name.
example: Lawrence
mobile_phone:
type: string
description: Customer phone (including extension).
example: (888)101-0011
nickname:
type: string
description: Nickname for this contact.
example: Ami
other_phone:
type: string
description: Other customer phone (including extension).
example: (888)100-0001
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
tax_region:
type: string
description: A region defined in your Zuora Tax rules.
example: Georgia
work_email:
type: string
description: Customer work email.
example: alawrence@zuora.com
work_phone:
type: string
description: Customer work phone.
example: (888)976-9056
other_phone_type:
type: string
enum:
- work
- mobile
- home
- other
description: The type of the additional phone number.
fax:
type: string
description: The contact's fax number.
accountPreviewRequest:
type: object
title: AccountPreviewRequest
description: ''
additionalProperties: false
properties:
exclude:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one-time, recurring, and usage.
include_draft_items:
type: boolean
description: Indicates whether to include items in the draft status.
include_evergreen_subscriptions:
type: boolean
description: Indicates whether to include evergreen subscriptions.
target_date:
type: string
format: date
description: >-
The target date is used to determine which charges to bill. All
unbilled charges as of or prior to the target date are included.
Zuora automatically keeps track of all charges that need to be
billed and that have not been billed prior to the target date.
example: '2022-01-01'
required:
- target_date
creditMemoItemPreviewResponse:
type: object
title: CreditMemoItemPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
amount:
type: number
description: The total amount of this credit memo item.
subtotal:
type: number
description: The total amount of this credit memo item exclusive of tax.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item that this credit memo item is applied
to.
document_item_date:
type: string
format: date-time
description: The date when the credit memo item takes effect.
example: '2022-01-01T07:08:12-07:00'
document_item_number:
type: string
charge_type:
type: string
description: >-
Type of the charge. It can be one of the following types: one-time,
recurring, or usage.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
id:
type: string
description: Unique identifier of the object
processing_type:
type: string
enum:
- subscription_item
- discount
- prepayment
- tax
quantity:
type: number
description: The number of units of this item.
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this credit
memo item.
service_start_date:
type: string
description: >-
The start date of the service period associated with this credit
memo item. If the associated charge is a one-time fee, then this
date is the date of that charge.
service_end_date:
type: string
description: >-
The end date of the service period associated with this credit memo
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
sku_name:
type: string
description: The name of the SKU associated with this item
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the credit memo
item.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
invoiceItemPreviewResponse:
type: object
title: InvoiceItemPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
amount:
type: number
description: The total amount of this invoice item.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item or a debit memo item that this
discount item or credit memo item is applied to.
document_date:
type: string
format: date
example: '2022-01-01'
subscription_item_description:
type: string
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this invoice
item.
subscription_item_name:
type: string
subscription_item_number:
type: string
description: >-
Human-readable identifier of the subscription item. It can be
user-supplied.
charge_type:
type: string
description: >-
Type of the charge. It can be one of the following types: one-time,
recurring, or usage.
id:
type: string
description: Unique identifier of the object
processing_type:
type: string
enum:
- subscription_item
- discount
- prepayment
- tax
product_name:
type: string
quantity:
type: number
description: The number of units of this item.
service_start_date:
type: string
description: >-
The start date of the service period associated with this invoice
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
service_end_date:
type: string
description: >-
The end date of the service period associated with this invoice
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
subscription_id:
type: string
description: The identifier of the subscription associated with the invoice item.
subscription_number:
type: string
description: >-
The subscription number of the subscription associated with this
item.
subscription_name:
type: string
description: The name of the subscription associated with this item.
tax:
type: number
description: The amount of tax applied to the invoice item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
accountPreviewResponse:
type: object
title: AccountPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
account_id:
type: string
description: >-
The unique identifier of the customer account associated with these
items.
credit_memo_items:
type: array
items:
allOf:
- $ref: '#/components/schemas/creditMemoItemPreviewResponse'
invoice_items:
type: array
items:
allOf:
- $ref: '#/components/schemas/invoiceItemPreviewResponse'
taxIdentifier:
type: object
title: TaxIdentifier
description: An object that contains the VAT Identification number.
additionalProperties: false
properties:
id:
type: string
description: >-
Value Added Tax (VAT) ID. Each VAT ID must begin with the code of
the country code and followed by a block of digits or characters.
generateBillingDocumentsAccountRequest:
type: object
title: GenerateBillingDocumentsAccountRequest
description: ''
nullable: false
additionalProperties: false
properties:
post:
type: boolean
description: If true, invoices will be automatically posted.
example: true
renew:
type: boolean
description: If true, subscriptions will be automatically renewed.
example: true
charges_excluded:
type: array
description: >-
Charge type or types to be excluded. Can be one or multiple of the following values:
- `one_time`
- `recurring`
- `usage`
items:
type: string
credit_memo_reason_code:
type: string
description: >-
A code identifying the reason for the credit memo transaction that
is generated by the request. The value must be an existing reason
code. If you do not pass the field or pass the field with empty
value, Zuora uses the default reason code.
document_date:
type: string
format: date
description: The date when the credit memo is applied
example: '2023-01-01'
subscription_ids:
type: array
items:
type: string
description: >-
The IDs of the subscriptions that you want to create the billing
documents for. Each value must be the unique identifier of the
latest version of an active subscription.
target_date:
type: string
format: date
description: All unbilled items on or before this date are included.
example: '2023-01-01'
generateBillingDocumentsAccountResponse:
type: object
title: GenerateBillingDocumentsAccountResponse
description: ''
nullable: false
additionalProperties: false
properties:
credit_memos:
allOf:
- $ref: '#/components/schemas/creditMemoListResponse'
description: Array of credit memos.
invoices:
allOf:
- $ref: '#/components/schemas/invoiceListResponse'
description: Array of invoices.
billingDocumentSettings:
type: object
title: BillingDocumentSettings
description: Billing document settings for an account
additionalProperties: false
properties:
credit_memo_template_id:
type: string
description: >-
Identifier of the credit memo template associated with this
customer.
example: 2c92c08b6a8c978f016a9e0084622b62
debit_memo_template_id:
type: string
description: Identifier of the debit memo template associated with this customer.
example: 2c92c08c6a8c7e08016a9ec8d72f3ab5
email_documents:
type: boolean
description: Whether the customer wants to receive email invoices.
example: alawrence@zuora.com
print_documents:
type: boolean
description: Whether the customer wants to receive printed invoices.
example: false
invoice_template_id:
type: string
description: Identifier of the invoice template associated with this customer.
example: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
type: array
items:
type: string
description: A list of additional email addresses to receive email notifications.
example: jdoe@zuora.com
taxCertificate:
type: object
title: TaxCertificate
description: The tax certificate information.
additionalProperties: false
properties:
company_code:
type: string
description: >-
Unique code that identifies a company account in Avalara. Use this
field to calculate taxes based on country of origin and sold-to
addresses in Avalara.
example: ABC
id:
type: string
description: Identifier of the tax exemption certificate.
start_date:
type: string
format: date
description: The tax certificate start date.
example: '2022-01-01'
description:
type: string
description: Description of the tax exemption certificate.
entity_use_code:
type: string
description: >-
A unique entity use code used by Avalara to apply exemptions. This
field is required only when you choose Avalara as your tax engine.
See [Exempt
Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)
for more information.
end_date:
type: string
format: date
description: The tax certificate end date.
example: '2023-01-01'
issuing_jurisdiction:
type: string
description: Typically, this is a state or government agency
example: Georgia
state:
type: string
enum:
- pending
- verified
- not_valid
description: >-
Status of the tax exemption certificate, indication whether the
certificate has been verified.
tax_identifier:
type: string
deprecated: true
description: >-
Value Added Tax (VAT) ID. Each VAT ID must begin with the code of
the country code and followed by a block of digits or characters.
example: DE123456789
taxationItem:
type: object
title: TaxationItem
description: taxation information for this billing document item.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the taxation item related to the invoice. Only
applicable for credit memos created from invoices.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
jurisdiction:
type: string
maxLength: 32
description: >-
The jurisdiction that applies the tax or VAT. This value is
typically a state, province, county, or city.
location_code:
type: string
maxLength: 32
description: >-
The identifier for the location based on the value of the `tax_code`
field.
name:
type: string
maxLength: 128
description: The name of the taxation item.
amount:
type: number
description: The amount of the tax applied to the total price.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_code_name:
type: string
description: The amount of the tax applied to the total price.
tax_date:
type: string
format: date
description: The date on which the tax is applied.
example: '2022-01-01'
tax_rate:
type: number
description: The amount of the tax applied to the total price.
tax_rate_name:
type: string
description: >-
The name of the tax rate, such as sales tax or GST. This name is
displayed on billing documents.
amount_exempt:
type: number
description: The calculated tax amount excluded due to the exemption.
source_tax_item_id:
type: string
description: >-
The ID of the taxation item of the invoice, from which the credit or
debit memo is created. This field is only applicable when the `type`
of the billing document is `credit_memo` and `debit_memo`.
remaining_balance:
type: number
readOnly: true
description: The remaining balance of the taxation item.
amount_credited:
type: number
readOnly: true
description: The credit memo amount applied to the taxation item.
amount_paid:
type: number
readOnly: true
description: The payment amount applied to the taxation item.
amount_refunded:
type: number
readOnly: true
description: The refund amount applied to the taxation item.
amount_applied:
type: number
readOnly: true
description: The credit memo item amount applied to the taxation item.
sales_tax_payable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
tax_inclusive:
type: boolean
description: If set to `true`, it indicates that amounts are inclusive of tax.
tax_rate_type:
type: string
enum:
- percent
- amount
description: Indicates whether the tax rate is an amount or a percentage.
taxationItemListResponse:
type: object
title: TaxationItemListResponse
description: Information of the taxation items.
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/taxationItem'
taxationItemPatchRequest:
type: object
title: TaxationItemPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
amount_exempt:
type: number
description: The calculated tax amount excluded due to the exemption.
invoice_item_id:
type: string
description: >-
Unique identifier of the invoice item to which the taxation item
applies. **This field is required if you are creating a credit memo
or debit memo from an invoice, and is not applicable if you are
creating an invoice.**.
jurisdiction:
type: string
maxLength: 32
description: >-
The jurisdiction that applies the tax or VAT. This value is
typically a state, province, county, or city.
location_code:
type: string
maxLength: 32
description: >-
The identifier for the location based on the value of the `tax_code`
field.
name:
type: string
maxLength: 128
description: The name of the taxation item.
amount:
type: number
description: The amount of the tax applied to the total price.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_code_name:
type: string
description: The amount of the tax applied to the total price.
tax_date:
type: string
format: date
description: The date on which the tax is applied.
example: '2022-01-01'
tax_rate:
type: number
description: The amount of the tax applied to the total price.
tax_rate_name:
type: string
description: >-
The name of the tax rate, such as sales tax or GST. This name is
displayed on billing documents.
tax_rate_type:
type: string
enum:
- percent
- amount
description: Indicates whether the tax rate is an amount or a percentage.
source_tax_item_id:
type: string
description: >-
The ID of the taxation item of the invoice, from which the credit or
debit memo is created. This field is only applicable when the `type`
of the billing document is `credit_memo` and `debit_memo`.
tax_inclusive:
type: boolean
description: If set to `true`, it indicates that amounts are inclusive of tax.
sales_tax_payable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
taxationItemCreateRequest:
type: object
title: TaxationItemCreateRequest
description: ''
additionalProperties: false
properties:
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
amount_exempt:
type: number
description: The calculated tax amount excluded due to the exemption.
invoice_item_id:
type: string
description: >-
Unique identifier of the invoice item to which the taxation item
applies. **This field is required if you are creating a credit memo
or debit memo from an invoice, and is not applicable if you are
creating an invoice.**.
jurisdiction:
type: string
maxLength: 32
description: >-
The jurisdiction that applies the tax or VAT. This value is
typically a state, province, county, or city.
location_code:
type: string
maxLength: 32
description: >-
The identifier for the location based on the value of the `tax_code`
field.
name:
type: string
maxLength: 128
description: The name of the taxation item.
amount:
type: number
description: The amount of the tax applied to the total price.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_code_name:
type: string
description: The amount of the tax applied to the total price.
tax_date:
type: string
format: date
description: The date on which the tax is applied.
example: '2022-01-01'
tax_rate:
type: number
description: The amount of the tax applied to the total price.
tax_rate_name:
type: string
description: >-
The name of the tax rate, such as sales tax or GST. This name is
displayed on billing documents.
tax_rate_type:
type: string
enum:
- percent
- amount
description: Indicates whether the tax rate is an amount or a percentage.
source_tax_item_id:
type: string
description: >-
The ID of the taxation item of the invoice, from which the credit or
debit memo is created. This field is only applicable when the `type`
of the billing document is `credit_memo` and `debit_memo`.
tax_inclusive:
type: boolean
description: If set to `true`, it indicates that amounts are inclusive of tax.
required:
- tax_date
- name
- amount
- tax_code
- tax_rate
customerAcceptanceMandate:
type: object
title: CustomerAcceptanceMandate
description: Details about the customer’s acceptance of the mandate.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: A reference to the consent agreement you have with your customer.
date:
type: string
format: date
readOnly: true
description: The date on which the customer accepted the mandate.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be used to
initiate a payment.
cardMandate:
type: object
title: CardMandate
description: >-
A mandate is a record of the permission a customer has given you to
debit their payment method. This hash contains details about the
mandate.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be used to
initiate a payment.
network_transaction_id:
type: string
readOnly: true
description: Identifier of a network transaction.
example: '1234567890'
customer_acceptance:
allOf:
- $ref: '#/components/schemas/customerAcceptanceMandate'
readOnly: true
description: A reference to the consent agreement you have with your customer.
type:
type: string
enum:
- multi_use
- single_use
readOnly: true
description: Indicates the type of the stored credential profile, if any.
verified:
type: boolean
readOnly: true
description: >-
Indicates the mandate was verified with the payment gateway by
Zuora.
example: true
verify:
type: boolean
description: Specifies if Zuora should verify this mandate.
example: false
ccRefMandate:
type: object
title: CcRefMandate
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
paypalExpress:
type: object
title: PaypalExpress
description: >-
If it is a `paypal_express` payment method, this hash contains details
about the PayPal Express payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: Email address associated with the payment method
required:
- baid
- email
paypalAdaptive:
type: object
title: PaypalAdaptive
description: >-
If it is a `paypal_adaptive` payment method, this hash contains details
about the PayPal Adaptive payment method.
additionalProperties: false
properties:
preapproval_key:
type: string
description: PayPal preapproval key.
example: 2G4EPFSD
email:
type: string
description: Email address associated with the payment method.
example: alawrence@zuora.com
required:
- preapproval_key
- email
paypalExpressNative:
type: object
title: PaypalExpressNative
description: >-
If it is a `paypal_express_native` payment method, this hash contains
details about the PayPal Express Native payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: >-
Email address associated with the payment method. This is required
with a paypal_express_checkout or a paypal_adaptive payment method.
required:
- baid
nzBecsDebit:
type: object
title: NzBecsDebit
description: >-
If the `type` of the payment method is `nz_becs_debit`, this hash
contains details about the BECS-NZ bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
padDebit:
type: object
title: PadDebit
description: >-
If the `type` of the payment method is `pad_debit`, this hash contains
details about the PAD bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
auBecsDebit:
type: object
title: AuBecsDebit
description: >-
If the `type` of the payment method is `au_becs_debit`, this hash
contains details about the BECS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
bacsDebit:
type: object
title: BacsDebit
description: >-
If the `type` of the payment method is `bacs_debit`,, this hash contains
details about the BACS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- bank_code
autogiroDebit:
type: object
title: AutogiroDebit
description: >-
If the `type` of the payment method is `autogiro_debit`, this hash
contains details about the Autogiro bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Autogiro (Direct Debit SE).
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- identity_number
- branch_code
betalingsDebit:
type: object
title: BetalingsDebit
description: >-
If the `type` of the payment method is `betalings_debit`, this hash
contains details about the Betalingsservice bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Betalingsservice (Direct Debit DK).
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- identity_number
- bank_code
achDebit:
type: object
title: AchDebit
description: >-
If the `type` of the payment method is `ach_debit`, this hash contains
details about the ACH bank account.
additionalProperties: false
properties:
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
bank_aba_code:
type: string
description: The nine-digit routing number or ABA number used by banks.
bank_account_name:
type: string
description: >-
The name of the account holder, which can be either a person or a
company.
bank_account_type:
type: string
enum:
- business_saving
- business_checking
- checking
- saving
description: The type of bank account associated with the payment method.
bank_name:
type: string
description: Name of the bank associated with this bank account.
bank_account_number:
type: string
description: The bank account number of the account holder.
required:
- bank_aba_code
- bank_account_type
- bank_account_name
- bank_account_number
- bank_name
achDebitUpdate:
type: object
title: AchDebitUpdate
description: ''
nullable: false
additionalProperties: false
properties:
mandate:
$ref: '#/components/schemas/mandate'
bank_aba_code:
type: string
description: The nine-digit routing number or ABA number used by banks.
bank_account_name:
type: string
description: >-
The name of the account holder, which can be either a person or a
company.
bank_account_type:
type: string
enum:
- business_saving
- business_checking
- checking
- saving
description: The type of bank account associated with the payment method.
bank_name:
type: string
description: Name of the bank associated with this bank account.
sepaDebit:
type: object
title: SepaDebit
description: >-
If the `type` of the payment method is `sepa_debit`, this hash contains
details about the SEPA bank account.
additionalProperties: false
properties:
IBAN:
type: string
description: >-
International Bank Account Number used to create the SEPA Debit
payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
business_identification_code:
type: string
description: The BIC code used with the Sepa Debit payment method.
required:
- IBAN
ccRef:
type: object
title: CcRef
description: >-
If the `type` of the payment method is `cc_ref`, this hash contains
details about the Credit Card Reference Transactions payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
second_token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment method
data. This field is conditionally required only when `token` is
being used to represent a gateway customer profile.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment method
data or represents a gateway's unique customer profile. When `token`
is used to represent a customer profile, `second_token` is
conditionally required for representing the underlying tokenized
payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
card:
type: object
title: CcRefCard
description: ''
nullable: false
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's expiration
year.
example: 2024
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
required:
- token
ccRefUpdate:
type: object
title: CcRefUpdate
description: >-
If the `type` of the payment method is `cc_ref`, this hash contains
details about the Credit Card Reference Transactions payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
second_token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment method
data. This field is conditionally required only when `token` is
being used to represent a gateway customer profile.
mandate:
$ref: '#/components/schemas/mandate'
card:
type: object
title: Card
description: >-
Credit card information. When providing a card number, you must meet the
requirements for PCI compliance. We strongly recommend using Zuora's
[Payment Pages
2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0)
instead of interacting with this API directly.
additionalProperties: false
properties:
card_number:
type: string
writeOnly: true
description: The card number, as a string without any separators.
example: '4001100010112042'
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: Two- or four-digit number representing the card's expiration year.
example: 2024
security_code:
type: string
description: >-
Card security code. It is highly recommended to always include this
value.
example: '111'
mandate:
$ref: '#/components/schemas/cardMandate'
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
required:
- card_number
- brand
- expiry_month
- expiry_year
getCardList:
type: object
title: GetCardList
description: Credit card information.
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: Two- or four-digit number representing the card's expiration year.
example: 2024
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
applePay:
type: object
title: ApplePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash contains
details about the Apple Pay payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you must meet
the requirements for PCI compliance. We strongly recommend using
Zuora.js instead of interacting with this API directly.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card Reference
Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by the
payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
payment_id:
type: string
description: >-
The ID of newly processed payment. Only available in the response of
the Create Payment Method API request.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment method
data or represents a gateway's unique customer profile. When `token`
is used to represent a customer profile, `second_token` is
conditionally required for representing the underlying tokenized
payment method.
cardUpdate:
type: object
title: CardUpdate
description: >-
If the `type` of the payment method is `card`, this hash contains
details about the Credit Card payment method. When providing a card
number, you must meet the requirements for PCI compliance. We strongly
recommend using Zuora's [Payment Pages
2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0)
instead of interacting with this API directly.
additionalProperties: false
properties:
expiry_month:
type: number
description: One- or two-digit expiration month (1-12) of the credit card.
expiry_year:
type: number
description: Two- or four-digit number representing the card's expiration year.
security_code:
type: string
description: >-
Card security code. It is highly recommended to always include this
value.
applePayCreate:
type: object
title: ApplePayCreate
description: >-
If the `type` of the payment method is `apple_pay`, this hash contains
details about the Apple Pay payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
The Merchant ID that was configured for use with Apple Pay in the
Apple iOS Developer Center.
customer_token:
type: object
additionalProperties: true
description: >-
The complete JSON Object representing the encrypted payment token
payload returned in the response from the Apple Pay session.
collect_payment:
type: boolean
description: >
A boolean flag to control whether a payment should be
processed after creating payment method. The payment amount
will be equivalent to the amount the merchant supplied in the
ApplePay session. Default is false.
If this field is set to `true`, you must specify the
`gateway_id` field with the payment gateway instance name.
If this field is set to `false`:
- The default payment gateway of your Zuora customer account will be used no matter whether a payment gateway instance is specified in the `gateway_id` field.
- You must select the **Verify new credit card** check box on the gateway instance settings page. Otherwise, the cryptogram will not be sent to the gateway.
- A separate subscribe or payment API call is required after this payment method creation call.
invoice_id:
type: string
description: >-
The id of invoice this payment will apply to. Note: When
`collect_payment` is true, this field is required. Only one
invoice can be paid; for scenarios where you want to pay for
multiple invoices, set collect_payment to false and use [Create
Payment](#operation/createPayment) API separately.
mandate:
$ref: '#/components/schemas/mandate'
required:
- customer_token
googlePayCreate:
type: object
title: GooglePayCreate
description: >-
If the `type` of the payment method is `google_pay`, this hash contains
details about the Google Pay payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
customer_token:
type: object
additionalProperties: true
description: >-
The complete JSON Object representing the encrypted payment token
payload returned in the response from the Google Pay session.
required:
- customer_token
googlePay:
type: object
title: GooglePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash contains
details about the Apple Pay payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you must meet
the requirements for PCI compliance. We strongly recommend using
Zuora.js instead of interacting with this API directly.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment method
data or represents a gateway's unique customer profile. When `token`
is used to represent a customer profile, `second_token` is
conditionally required for representing the underlying tokenized
payment method.
billingDetails:
type: object
title: BillingDetails
description: >-
Billing information associated with the payment method that may be used
or required by specific payment method types.
additionalProperties: false
properties:
name:
type: string
description: Customer full name or business name.
example: Amy Lawrence
address:
type: object
title: AddressFieldDefinitions
description: Address information used in billing details.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: Address line 2 (e.g., apartment, suite, unit, or building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
country:
type: string
description: The country of the contact's address.
example: United States
state:
type: string
description: The state, county, province, or region.
example: GA
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
phone:
type: string
description: Customer phone (including extension).
example: (888)976-9056
account:
type: object
title: Account
description: The account data.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_number:
type: string
description: Human-readable identifier of the account. It can be user-supplied.
example: A-100001
billing_document_settings:
type: object
title: BillingDocumentSettings
description: Billing document settings for an account
additionalProperties: false
properties:
credit_memo_template_id:
type: string
description: >-
Identifier of the credit memo template associated with this
customer.
example: 2c92c08b6a8c978f016a9e0084622b62
debit_memo_template_id:
type: string
description: >-
Identifier of the debit memo template associated with this
customer.
example: 2c92c08c6a8c7e08016a9ec8d72f3ab5
email_documents:
type: boolean
description: Whether the customer wants to receive email invoices.
example: alawrence@zuora.com
print_documents:
type: boolean
description: Whether the customer wants to receive printed invoices.
example: false
invoice_template_id:
type: string
description: >-
Identifier of the invoice template associated with this
customer.
example: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
type: array
items:
type: string
description: >-
A list of additional email addresses to receive email
notifications.
example: jdoe@zuora.com
batch:
type: string
description: The identifier of a bill run batch.
bill_cycle_day:
type: integer
minimum: 0
maximum: 31
description: >-
The day of the month on which your customer will be invoiced. For
month-end specify 31.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: Customer billing address.
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: Customer address used for calculating tax.
communication_profile_id:
type: string
description: >-
Identifier of the communication profile associated with this
customer.
example: 2c92c0946a6dffc0016a7faab604299b
crm_id:
type: string
description: CRM account identifier.
example: 1a2b3c4d5e
default_payment_method_id:
type: string
description: Identifier of the default payment method on the customer account.
example: 8a95b1946b6aeac8718c32aab8c395f
name:
type: string
description: The name of the customer account.
example: test account
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
parent_account_id:
type: string
description: Identifier of this customer's parent account, if any.
example: 8ad093f27d6eee80017d6effd7a66759
payment_gateway:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: Payment gateway name.
example: adyen gateway
payment_terms:
type: string
description: >-
Payment terms configured in **Billing Settings > Payment Terms** of
your Zuora tenant.
example: Net 30
sequence_set_id:
type: string
description: >-
The identifier or the billing document sequence set that is assigned
to the customer account.
example: 2c92a4204a6dffc0016a7faab723041c
auto_pay:
type: boolean
description: >-
Controls whether future payments are automatically billed when they
are due.
example: true
tax_certificate:
type: object
title: TaxCertificate
description: The tax certificate information.
additionalProperties: false
properties:
company_code:
type: string
description: >-
Unique code that identifies a company account in Avalara. Use
this field to calculate taxes based on country of origin and
sold-to addresses in Avalara.
example: ABC
id:
type: string
description: Identifier of the tax exemption certificate.
start_date:
type: string
format: date
description: The tax certificate start date.
example: '2022-01-01'
description:
type: string
description: Description of the tax exemption certificate.
entity_use_code:
type: string
description: >-
A unique entity use code used by Avalara to apply exemptions.
This field is required only when you choose Avalara as your tax
engine. See [Exempt
Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)
for more information.
end_date:
type: string
format: date
description: The tax certificate end date.
example: '2023-01-01'
issuing_jurisdiction:
type: string
description: Typically, this is a state or government agency
example: Georgia
state:
type: string
enum:
- pending
- verified
- not_valid
description: >-
Status of the tax exemption certificate, indication whether the
certificate has been verified.
tax_identifier:
type: string
deprecated: true
description: >-
Value Added Tax (VAT) ID. Each VAT ID must begin with the code
of the country code and followed by a block of digits or
characters.
example: DE123456789
tax_identifier:
type: object
title: TaxIdentifier
description: An object that contains the VAT Identification number.
additionalProperties: false
properties:
id:
type: string
description: >-
Value Added Tax (VAT) ID. Each VAT ID must begin with the code
of the country code and followed by a block of digits or
characters.
currency:
type: string
description: >-
Three-letter ISO currency code. Once the currency is set for an
account, it cannot be updated.
example: USD
sales_rep:
type: string
description: The name of the sales representative associated with this account
example: Max
enabled:
type: boolean
readOnly: true
description: >-
Usually used to disable the customer account. The default is true.
If false, attempts to create subscriptions for the customer account
will fail.
example: true
remaining_debit_memo_balance:
type: number
readOnly: true
description: Total remaining balance of all posted debit memos.
example: 10
remaining_invoice_balance:
type: number
readOnly: true
description: Total remaining balance of all posted invoices.
example: 100
remaining_credit_memo_balance:
type: number
readOnly: true
description: Total remaining balance of all posted credit memos.
example: 50
remaining_payment_balance:
type: number
readOnly: true
description: Total remaining balance of all posted payments.
example: 20
bill_to_id:
type: string
description: Customer billing address.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to_id:
type: string
description: Customer address used for calculating tax.
example: 8ad0823f8040e52d0180433026b156fe
default_payment_method:
allOf:
- $ref: '#/components/schemas/paymentMethod'
description: The default payment method for the customer.
billing_documents:
allOf:
- $ref: '#/components/schemas/billingDocumentListResponse'
readOnly: true
description: List of customer billing documents.
payments:
allOf:
- $ref: '#/components/schemas/paymentListResponse'
readOnly: true
description: List of customer payments.
payment_methods:
allOf:
- $ref: '#/components/schemas/paymentMethodListResponse'
readOnly: true
description: List of customer payment methods.
subscriptions:
allOf:
- $ref: '#/components/schemas/subscriptionListResponse'
readOnly: true
description: List of customer subscriptions.
usage_records:
allOf:
- $ref: '#/components/schemas/listUsageResponse'
readOnly: true
description: List of customer usages.
credit_memos:
allOf:
- $ref: '#/components/schemas/creditMemoListResponse'
readOnly: true
description: List of credit memo
debit_memos:
allOf:
- $ref: '#/components/schemas/debitMemoListResponse'
readOnly: true
description: List of debit memo
invoices:
allOf:
- $ref: '#/components/schemas/invoiceListResponse'
readOnly: true
description: List of invoices
listAccountResponse:
type: object
title: ListAccountResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/account'
listContactResponse:
type: object
title: ListContactResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/contact'
paymentMethodAuthorizationResponse:
type: object
title: PaymentMethodAuthorizationResponse
description: ''
nullable: false
additionalProperties: false
properties:
auth_transaction_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
electronic payment gateway when a payment is created. If not
specified, the payment number will be passed in instead. Gateways
check duplicates on the gateway order ID to ensure that the merchant
do not accidentally enter the same transaction twice. This ID can
also be used to do reconciliation and tie the payment to a natural
key in external systems. The source of this ID varies by merchant.
Some merchants use their shopping cart order IDs, and others use
something different. Merchants use this ID to track transactions in
their eCommerce systems. When you create a payment for capturing the
authorized funds, it is highly recommended to pass in the
`gateway_order_id` that you used when authorizing the funds by using
the Create authorization operation, together with the
`authorization_id` field.
state:
type: string
enum:
- approved
- queued_for_submission
description: The status of the payment authorization.
authorizationMandate:
type: object
title: AuthorizationMandate
description: ''
nullable: false
additionalProperties: false
properties:
type:
type: string
enum:
- multi_use
- single_use
description: Indicates the type of mandate, if any.
paymentMethod:
type: object
title: PaymentMethod
description: Payment method information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
enum:
- paypal_express
- paypal_express_native
- paypal_adaptive
- card
- cc_ref
- ach_debit
- sepa_debit
- betalings_debit
- autogiro_debit
- bacs_debit
- au_becs_debit
- nz_becs_debit
- pad_debit
- apple_pay
- wire_transfer
- check
- cash
- other
- paypal
- adyen_google_pay
- adyen_apple_pay
description: >-
The type of the payment method. An additional hash is included on
the payment method with a name matching this value. It contains
additional information specific to the payment method type.
custom_type:
type: string
description: >-
The custom type of the payment method from Universal Payment
Connector.
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account:
allOf:
- $ref: '#/components/schemas/account'
readOnly: true
description: The customer account associated with this payment method.
billing_details:
type: object
title: BillingDetails
description: >-
Billing information associated with the payment method that may be
used or required by specific payment method types.
additionalProperties: false
properties:
name:
type: string
description: Customer full name or business name.
example: Amy Lawrence
address:
type: object
title: AddressFieldDefinitions
description: Address information used in billing details.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: Address line 2 (e.g., apartment, suite, unit, or building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
country:
type: string
description: The country of the contact's address.
example: United States
state:
type: string
description: The state, county, province, or region.
example: GA
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
phone:
type: string
description: Customer phone (including extension).
example: (888)976-9056
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts using
this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
ip_address:
type: string
nullable: true
description: The IP address from which the Mandate was accepted by the customer.
example: 192.10.1.123
bank_identification_number:
type: string
card:
type: object
title: GetCardList
description: Credit card information.
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's expiration
year.
example: 2024
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
paypal_express_native:
type: object
title: PaypalExpressNative
description: >-
If it is a `paypal_express_native` payment method, this hash
contains details about the PayPal Express Native payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: >-
Email address associated with the payment method. This is
required with a paypal_express_checkout or a paypal_adaptive
payment method.
required:
- baid
paypal_express:
type: object
title: PaypalExpress
description: >-
If it is a `paypal_express` payment method, this hash contains
details about the PayPal Express payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: Email address associated with the payment method
required:
- baid
- email
paypal_adaptive:
type: object
title: PaypalAdaptive
description: >-
If it is a `paypal_adaptive` payment method, this hash contains
details about the PayPal Adaptive payment method.
additionalProperties: false
properties:
preapproval_key:
type: string
description: PayPal preapproval key.
example: 2G4EPFSD
email:
type: string
description: Email address associated with the payment method.
example: alawrence@zuora.com
required:
- preapproval_key
- email
sepa_debit:
type: object
title: SepaDebit
description: >-
If the `type` of the payment method is `sepa_debit`, this hash
contains details about the SEPA bank account.
additionalProperties: false
properties:
IBAN:
type: string
description: >-
International Bank Account Number used to create the SEPA Debit
payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
business_identification_code:
type: string
description: The BIC code used with the Sepa Debit payment method.
required:
- IBAN
cc_ref:
type: object
title: CcRef
description: >-
If the `type` of the payment method is `cc_ref`, this hash contains
details about the Credit Card Reference Transactions payment method.
See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
second_token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data. This field is conditionally required only when
`token` is being used to represent a gateway customer profile.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer profile.
When `token` is used to represent a customer profile,
`second_token` is conditionally required for representing the
underlying tokenized payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
card:
type: object
title: CcRefCard
description: ''
nullable: false
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's expiration
year.
example: 2024
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
required:
- token
apple_pay:
type: object
title: ApplePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See [Supported
payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you must
meet the requirements for PCI compliance. We strongly recommend
using Zuora.js instead of interacting with this API directly.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
payment_id:
type: string
description: >-
The ID of newly processed payment. Only available in the
response of the Create Payment Method API request.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer profile.
When `token` is used to represent a customer profile,
`second_token` is conditionally required for representing the
underlying tokenized payment method.
google_pay:
type: object
title: GooglePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See [Supported
payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you must
meet the requirements for PCI compliance. We strongly recommend
using Zuora.js instead of interacting with this API directly.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer profile.
When `token` is used to represent a customer profile,
`second_token` is conditionally required for representing the
underlying tokenized payment method.
ach_debit:
type: object
title: AchDebit
description: >-
If the `type` of the payment method is `ach_debit`, this hash
contains details about the ACH bank account.
additionalProperties: false
properties:
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
bank_aba_code:
type: string
description: The nine-digit routing number or ABA number used by banks.
bank_account_name:
type: string
description: >-
The name of the account holder, which can be either a person or
a company.
bank_account_type:
type: string
enum:
- business_saving
- business_checking
- checking
- saving
description: The type of bank account associated with the payment method.
bank_name:
type: string
description: Name of the bank associated with this bank account.
bank_account_number:
type: string
description: The bank account number of the account holder.
required:
- bank_aba_code
- bank_account_type
- bank_account_name
- bank_account_number
- bank_name
betalings_debit:
type: object
title: BetalingsDebit
description: >-
If the `type` of the payment method is `betalings_debit`, this hash
contains details about the Betalingsservice bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Betalingsservice (Direct Debit DK).
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- identity_number
- bank_code
autogiro_debit:
type: object
title: AutogiroDebit
description: >-
If the `type` of the payment method is `autogiro_debit`, this hash
contains details about the Autogiro bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Autogiro (Direct Debit SE).
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- identity_number
- branch_code
bacs_debit:
type: object
title: BacsDebit
description: >-
If the `type` of the payment method is `bacs_debit`,, this hash
contains details about the BACS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- bank_code
au_becs_debit:
type: object
title: AuBecsDebit
description: >-
If the `type` of the payment method is `au_becs_debit`, this hash
contains details about the BECS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
nz_becs_debit:
type: object
title: NzBecsDebit
description: >-
If the `type` of the payment method is `nz_becs_debit`, this hash
contains details about the BECS-NZ bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
pad_debit:
type: object
title: PadDebit
description: >-
If the `type` of the payment method is `pad_debit`, this hash
contains details about the PAD bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: Identifier of the bank branch associated with this bank account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated by
the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it can be
used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
state:
type: string
enum:
- active
- closed
- scrubbed
description: The state of the payment method.
auto_generated:
type: boolean
use_default_retry_rule:
type: boolean
existing_mandate:
type: boolean
last_failed_sale_transaction_time:
type: string
format: date-time
last_transaction_time:
type: string
format: date-time
last_transaction_status:
type: string
number_of_consecutive_failures:
type: integer
total_number_of_processed_payments:
type: integer
total_number_of_error_payments:
type: integer
paymentMethodAuthorizationRequest:
type: object
title: PaymentMethodAuthorizationRequest
description: ''
additionalProperties: false
properties:
account_id:
type: string
description: >-
A customer account identifier. Either `account_id` or
`account_number` is required.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account_number:
type: string
description: >-
A Human-readable customer account identifier. Either `account_id` or
`account_number` is required.
example: RC-00000011
amount:
type: number
description: Amount to be authorized.
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
the payments that are made with this payment method. If you do not
set this field, Zuora will use one of the following payment gateways
instead: The default payment gateway of the customer account that
owns the payment method, if the payment method is associated with a
customer account or the default payment gateway of your Zuora
tenant.
example: 8ad093d07ae636bb017ae97518762aa3
gateway_options:
type: object
additionalProperties:
type: string
description: A hash containing gateway-specific parameters.
example:
key: value
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
electronic payment gateway when a payment is created. If not
specified, the payment number will be passed in instead. Gateways
check duplicates on the gateway order ID to ensure that the merchant
do not accidentally enter the same transaction twice. This ID can
also be used to do reconciliation and tie the payment to a natural
key in external systems. The source of this ID varies by merchant.
Some merchants use their shopping cart order IDs, and others use
something different. Merchants use this ID to track transactions in
their eCommerce systems. When you create a payment for capturing the
authorized funds, it is highly recommended to pass in the
`gateway_order_id` that you used when authorizing the funds by using
the Create authorization operation, together with the
`authorization_id` field.
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
mandate:
$ref: '#/components/schemas/authorizationMandate'
required:
- amount
- gateway_order_id
paymentMethodVoidAuthorizationRequest:
type: object
title: PaymentMethodVoidAuthorizationRequest
description: ''
additionalProperties: false
properties:
account_id:
type: string
description: >-
A customer account identifier. Either `account_id` or
`account_number` is required.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account_number:
type: string
description: >-
A Human-readable customer account identifier. Either `account_id` or
`account_number` is required.
example: RC-00000011
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
the payments that are made with this payment method. If you do not
set this field, Zuora will use one of the following payment gateways
instead: The default payment gateway of the customer account that
owns the payment method, if the payment method is associated with a
customer account or the default payment gateway of your Zuora
tenant.
example: 8ad093d07ae636bb017ae97518762aa3
gateway_options:
type: object
additionalProperties:
type: string
description: A hash containing gateway-specific parameters.
example:
key: value
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
electronic payment gateway when a payment is created. If not
specified, the payment number will be passed in instead. Gateways
check duplicates on the gateway order ID to ensure that the merchant
do not accidentally enter the same transaction twice. This ID can
also be used to do reconciliation and tie the payment to a natural
key in external systems. The source of this ID varies by merchant.
Some merchants use their shopping cart order IDs, and others use
something different. Merchants use this ID to track transactions in
their eCommerce systems. When you create a payment for capturing the
authorized funds, it is highly recommended to pass in the
`gateway_order_id` that you used when authorizing the funds by using
the Create authorization operation, together with the
`authorization_id` field.
auth_transaction_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
required:
- auth_transaction_id
- gateway_order_id
paymentMethodListResponse:
type: object
title: PaymentMethodListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/paymentMethod'
paymentMethodCreateRequest:
type: object
title: PaymentMethodCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
enum:
- paypal_express
- paypal_express_native
- paypal_adaptive
- card
- cc_ref
- ach_debit
- sepa_debit
- betalings_debit
- autogiro_debit
- bacs_debit
- au_becs_debit
- nz_becs_debit
- pad_debit
- apple_pay
- other
- paypal
- adyen_google_pay
- adyen_apple_pay
description: >-
The type of the payment method. An additional hash is included on
the payment method with a name matching this value. It contains
additional information specific to the payment method type.
This field enumerates the supported payment methods. Not all payment gateways support all these payment method types. Check <a href="https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods" target="_blank">Supported payment methods</a> to check the supported payment methods for each gateway.
If you need to create payment methods outside the scope of this operaton, you have to use the [Create a payment method](https://developer.zuora.com/v1-api-reference/api/operation/POST_PaymentMethods/) operation of the v1 API instead of the Quickstart API.
custom_type:
type: string
description: >-
The custom type of the payment method from Universal Payment
Connector.
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account:
allOf:
- $ref: '#/components/schemas/account'
readOnly: true
description: The customer account associated with this payment method.
billing_details:
$ref: '#/components/schemas/billingDetails'
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts using
this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
description: Identifier of the device browser session.
example: 2cadffe03
ip_address:
type: string
nullable: true
description: The IP address from which the Mandate was accepted by the customer.
example: 192.10.1.123
bank_identification_number:
type: string
description: >-
The first six or eight digits of the payment method's number, such
as the credit card number or account number. Banks use this number
to identify a payment method.
example: '123456'
card:
$ref: '#/components/schemas/card'
paypal_express_native:
$ref: '#/components/schemas/paypalExpressNative'
paypal_express:
$ref: '#/components/schemas/paypalExpress'
paypal_adaptive:
$ref: '#/components/schemas/paypalAdaptive'
sepa_debit:
$ref: '#/components/schemas/sepaDebit'
cc_ref:
$ref: '#/components/schemas/ccRef'
apple_pay:
$ref: '#/components/schemas/applePayCreate'
google_pay:
$ref: '#/components/schemas/googlePayCreate'
ach_debit:
$ref: '#/components/schemas/achDebit'
betalings_debit:
$ref: '#/components/schemas/betalingsDebit'
autogiro_debit:
$ref: '#/components/schemas/autogiroDebit'
bacs_debit:
$ref: '#/components/schemas/bacsDebit'
au_becs_debit:
$ref: '#/components/schemas/auBecsDebit'
nz_becs_debit:
$ref: '#/components/schemas/nzBecsDebit'
pad_debit:
$ref: '#/components/schemas/padDebit'
account_number:
type: string
description: >-
A human-readable customer account identifier. It can be
user-supplied.
example: A-100001
is_default:
type: boolean
description: >-
Indicates whether it is the default payment method on the associated
account.
example: false
gateway_id:
type: string
description: >-
Identifier of the payment gateway Zuora will use to authorize the
payments that are made with this payment method.
example: 8ad093d07ae636bb017ae97518762aa3
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
required:
- type
paymentMethodPatchRequest:
type: object
title: PaymentMethodPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
billing_details:
$ref: '#/components/schemas/billingDetails'
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account_number:
type: string
description: >-
A human-readable customer account identifier. It can be
user-supplied.
example: A-100001
custom_fields:
$ref: '#/components/schemas/customFields'
card:
allOf:
- $ref: '#/components/schemas/cardUpdate'
description: >-
Credit card information. When providing a card number, you must meet
the requirements for PCI compliance. We strongly recommend using
Zuora.js instead of interacting with this API directly.
cc_ref:
allOf:
- $ref: '#/components/schemas/ccRefUpdate'
description: >-
Credit Card Reference Transaction. See Supported payment methods for
payment gateways that support this type of payment method.
mandate:
allOf:
- $ref: '#/components/schemas/ccRefMandate'
ach_debit:
allOf:
- $ref: '#/components/schemas/achDebitUpdate'
description: >-
If this is an ach_debit payment method, this hash contains details
about the ACH debit bank account.
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts using
this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
description: Identifier of the device browser session.
example: 2cadffe03
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
currency:
type: string
description: 3-letter ISO 4217 currency code.
gateway_id:
type: string
description: >-
Identifier of the payment gateway Zuora will use to authorize the
payments that are made with this payment method.
accountPaymentMethodRequest:
type: object
title: AccountPaymentMethodRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
enum:
- paypal_express
- paypal_express_native
- paypal_adaptive
- card
- cc_ref
- ach_debit
- sepa_debit
- betalings_debit
- autogiro_debit
- bacs_debit
- au_becs_debit
- nz_becs_debit
- pad_debit
- apple_pay
- wire_transfer
- check
- cash
- other
- paypal
- adyen_google_pay
- adyen_apple_pay
description: >-
The type of the payment method. An additional hash is included on
the payment method with a name matching this value. It contains
additional information specific to the payment method type.
custom_type:
type: string
description: >-
The custom type of the payment method from Universal Payment
Connector.
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account:
allOf:
- $ref: '#/components/schemas/account'
readOnly: true
description: The customer account associated with this payment method.
billing_details:
$ref: '#/components/schemas/billingDetails'
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts using
this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
description: Identifier of the device browser session.
example: 2cadffe03
ip_address:
type: string
nullable: true
description: The IP address from which the Mandate was accepted by the customer.
example: 192.10.1.123
bank_identification_number:
type: string
description: >-
The first six or eight digits of the payment method's number, such
as the credit card number or account number. Banks use this number
to identify a payment method.
example: '123456'
card:
$ref: '#/components/schemas/card'
paypal_express_native:
$ref: '#/components/schemas/paypalExpressNative'
paypal_express:
$ref: '#/components/schemas/paypalExpress'
paypal_adaptive:
$ref: '#/components/schemas/paypalAdaptive'
sepa_debit:
$ref: '#/components/schemas/sepaDebit'
cc_ref:
$ref: '#/components/schemas/ccRef'
apple_pay:
$ref: '#/components/schemas/applePay'
google_pay:
$ref: '#/components/schemas/googlePay'
ach_debit:
$ref: '#/components/schemas/achDebit'
betalings_debit:
$ref: '#/components/schemas/betalingsDebit'
autogiro_debit:
$ref: '#/components/schemas/autogiroDebit'
bacs_debit:
$ref: '#/components/schemas/bacsDebit'
au_becs_debit:
$ref: '#/components/schemas/auBecsDebit'
nz_becs_debit:
$ref: '#/components/schemas/nzBecsDebit'
pad_debit:
$ref: '#/components/schemas/padDebit'
paymentMethodVerificationRequest:
type: object
title: PaymentMethodVerificationRequest
description: ''
nullable: false
additionalProperties: false
properties:
currency:
type: string
description: Three-letter ISO currency code.
security_code:
type: string
description: Card security code.
payment_gateway:
type: string
description: >-
The name of the payment gateway instance. If no value is specified
for this field, the default payment gateway of your Zuora tenant
will be used.
example: 8ad093d07ae636bb017ae97518762aa3
gateway_options:
type: object
additionalProperties:
type: string
description: A hash containing gateway-specific parameters.
example:
key: value
accountPatchRequest:
type: object
title: AccountPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_number:
type: string
description: Human-readable identifier of the account. It can be user-supplied.
example: A-100001
billing_document_settings:
$ref: '#/components/schemas/billingDocumentSettings'
batch:
type: string
description: The identifier of a bill run batch.
bill_cycle_day:
type: integer
minimum: 0
maximum: 31
description: >-
The day of the month on which your customer will be invoiced. For
month-end specify 31.
bill_to:
allOf:
- $ref: '#/components/schemas/accountContactPatchRequest'
description: Customer billing address.
sold_to:
allOf:
- $ref: '#/components/schemas/accountContactPatchRequest'
description: Customer address used for calculating tax.
communication_profile_id:
type: string
description: >-
Identifier of the communication profile associated with this
customer.
example: 2c92c0946a6dffc0016a7faab604299b
crm_id:
type: string
description: CRM account identifier.
example: 1a2b3c4d5e
default_payment_method_id:
type: string
description: Identifier of the default payment method on the customer account.
example: 8a95b1946b6aeac8718c32aab8c395f
name:
type: string
description: The name of the customer account.
example: test account
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
parent_account_id:
type: string
description: Identifier of this customer's parent account, if any.
example: 8ad093f27d6eee80017d6effd7a66759
payment_gateway:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: Payment gateway name.
example: adyen gateway
payment_terms:
type: string
description: >-
Payment terms configured in **Billing Settings > Payment Terms** of
your Zuora tenant.
example: Net 30
sequence_set_id:
type: string
description: >-
The identifier or the billing document sequence set that is assigned
to the customer account.
example: 2c92a4204a6dffc0016a7faab723041c
auto_pay:
type: boolean
description: >-
Controls whether future payments are automatically billed when they
are due.
example: true
tax_certificate:
$ref: '#/components/schemas/taxCertificate'
tax_identifier:
$ref: '#/components/schemas/taxIdentifier'
currency:
type: string
description: >-
Three-letter ISO currency code. Once the currency is set for an
account, it cannot be updated.
example: USD
sales_rep:
type: string
description: The name of the sales representative associated with this account
example: Max
accountCreateRequest:
type: object
title: AccountCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_number:
type: string
description: Human-readable identifier of the account. It can be user-supplied.
example: A-100001
billing_document_settings:
$ref: '#/components/schemas/billingDocumentSettings'
batch:
type: string
description: The identifier of a bill run batch.
bill_cycle_day:
type: integer
minimum: 0
maximum: 31
description: >-
The day of the month on which your customer will be invoiced. For
month-end specify 31.
bill_to:
allOf:
- $ref: '#/components/schemas/accountContactCreateRequest'
description: Customer billing address.
sold_to:
allOf:
- $ref: '#/components/schemas/accountContactCreateRequest'
description: Customer address used for calculating tax.
communication_profile_id:
type: string
description: >-
Identifier of the communication profile associated with this
customer.
example: 2c92c0946a6dffc0016a7faab604299b
crm_id:
type: string
description: CRM account identifier.
example: 1a2b3c4d5e
default_payment_method_id:
type: string
description: Identifier of the default payment method on the customer account.
example: 8a95b1946b6aeac8718c32aab8c395f
name:
type: string
description: The name of the customer account.
example: test account
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
parent_account_id:
type: string
description: Identifier of this customer's parent account, if any.
example: 8ad093f27d6eee80017d6effd7a66759
payment_gateway:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: Payment gateway name.
example: adyen gateway
payment_terms:
type: string
description: >-
Payment terms configured in **Billing Settings > Payment Terms** of
your Zuora tenant.
example: Net 30
sequence_set_id:
type: string
description: >-
The identifier or the billing document sequence set that is assigned
to the customer account.
example: 2c92a4204a6dffc0016a7faab723041c
auto_pay:
type: boolean
description: >-
Controls whether future payments are automatically billed when they
are due.
example: true
tax_certificate:
$ref: '#/components/schemas/taxCertificate'
tax_identifier:
$ref: '#/components/schemas/taxIdentifier'
currency:
type: string
description: >-
Three-letter ISO currency code. Once the currency is set for an
account, it cannot be updated.
example: USD
sales_rep:
type: string
description: The name of the sales representative associated with this account
example: Max
payment_method:
x-displayName: Get an Account
allOf:
- $ref: '#/components/schemas/accountPaymentMethodRequest'
description: |
A new payment method for the account.
Note that the Quickstart API does not support the creating payment methods through the Universal Payment Connector (UPC).
required:
- currency
- bill_to
- name
orderLineItemRevenue:
type: object
title: OrderLineItemRevenue
description: Accounting configuration if you have Zuora Revenue enabled.
additionalProperties: false
properties:
exclude_item_billing_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated billing document items are excluded
from the revenue accounting.
exclude_item_booking_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated subscription items are excluded
from the revenue accounting.
adjustment_revenue_account:
type: string
nullable: true
description: An active accounting code in your Zuora chart of accounts.
contract_recognized_revenue_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recognized_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
revenue_recognition_rule_name:
type: string
description: The revenue recognition rule for the order line item.
lineItem:
type: object
title: LineItem
description: Data of order line items.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the original price with a per-unit price.
target_date:
type: string
format: date
description: >-
The target date for the order line item to be picked up by bill run
for billing.
deferred_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
discount_unit_amount:
type: number
description: >-
Discount amount. Specify this field if you offer an amount-based
discount.
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
category:
type: string
enum:
- sale
- return
description: >-
The category for the order line item, to indicate a product sale or
return.
state:
type: string
enum:
- pending
- booked
- sent_to_billing
- complete
- canceled
description: >-
The state of an order line item. If you want to generate billing
documents for order line items, you must set this field to
`sent_to_billing`. For invoice preview, you do not need to set this
field.
type:
type: string
description: The type of the order line item.
name:
type: string
description: Name of the order line item
item_number:
type: string
description: >-
Human-readable identifier of the order item. It can be
user-supplied.
list_unit_price:
type: number
description: The list price per unit for the order line item.
product_code:
type: string
description: The product code for the order line item.
price_id:
type: string
description: Identifier of the price.
purchase_order_number:
type: string
description: >-
Used by customers to specify the Purchase Order Number provided by
the buyer.
quantity:
type: number
description: >-
The quantity of units, such as the number of authors in a hosted
wiki service.
recognized_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
revenue_recognition_rule_name:
type: string
description: The revenue recognition rule for the order line item.
sold_to_id:
type: string
description: Customer address used for calculating tax.
example: 8ad0823f8040e52d0180433026b156fe
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
start_date:
type: string
format: date
description: >-
The date a transaction starts. The default value of this field is
the order date.
example: '2022-01-01'
end_date:
type: string
format: date
description: >-
The date a transaction is completed. The default value of this field
is the transaction start date. Also, the value of this field should
always equal or be later than the value of the `start_date` field.
example: '2022-01-01'
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items. EXPANDABLE
related_subscription_number:
type: string
description: >-
Use this field to relate an order line item to an subscription.
Specify this field to the subscription number of the subscription to
relate.
billing_rule:
type: string
enum:
- trigger_without_fulfillment
- trigger_on_fulfillment
description: The billing rule for the Order Line Item.
total:
type: string
description: The total amount, including the total tax amount.
subtotal:
type: string
description: 'The total amount exclusive of tax. '
original_order_date:
type: string
format: date
description: >-
The date when the subscription item is created through an order.
This field is to standardize the booking date information to
increase audit ability and traceability of data between Zuora
Billing and Zuora Revenue. It is mapped as the booking date for a
sales order line in Zuora Revenue.
example: '2022-01-01'
accounting_code:
type: string
description: The accounting code for the order line item.
adjustment_liability_account:
type: string
description: >-
The accounting code on the Order Line Item object for customers
using Zuora Billing - Revenue Integration.
adjustment_revenue_account:
type: string
nullable: true
description: >-
The accounting code on the Order Line Item object for customers
using Zuora Billing - Revenue Integration.
discount_total:
type: string
description: The total discount amount.
list_price:
type: string
description: >-
The extended list price for an order line item, calculated by the
formula: listPrice = listPricePerUnit * quantity
original_sold_to_id:
type: string
description: >-
The ID of a contact that belongs to the billing account of the order
line item. Use this field to assign an existing account as the
sold-to contact of an order line item.
unbilled_receivables_account:
type: string
description: >-
The accounting code on the Order Line Item object for customers
using Zuora Billing - Revenue Integration.
orderLineItem:
type: object
title: OrderLineItem
description: Data of order line items.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
revenue:
type: object
title: OrderLineItemRevenue
description: Accounting configuration if you have Zuora Revenue enabled.
additionalProperties: false
properties:
exclude_item_billing_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated billing document items are
excluded from the revenue accounting.
exclude_item_booking_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated subscription items are excluded
from the revenue accounting.
adjustment_revenue_account:
type: string
nullable: true
description: An active accounting code in your Zuora chart of accounts.
contract_recognized_revenue_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recognized_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
revenue_recognition_rule_name:
type: string
description: The revenue recognition rule for the order line item.
unit_of_measure:
type: string
description: A configured unit of measure.
accounting_code:
type: string
description: An active accounting code in your Zuora chart of accounts.
adjustment_liability_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
unit_amount:
type: number
description: The unit amount to be charged.
target_date:
type: string
format: date
description: >-
All order line items that were unbilled on or before this date are
included in future bill runs.
billing_rule:
enum:
- trigger_without_fulfillment
- trigger_on_fulfillment
description: The billing rule for the order line item.
contract_asset_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
contract_liability_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
discount_unit_amount:
type: number
description: Discount amount per unit.
discount_percent:
type: number
description: Discount percent.
category:
enum:
- sale
- return
description: >-
The category for the order line item, to indicate a product sale or
return.
name:
type: string
description: The name of the order line item.
type:
enum:
- product
- fee
- services
description: The type of the order line item.
list_unit_price:
type: number
description: The list price per unit for the order line item.
product_code:
type: string
description: The product code for the order line item.
purchase_order_number:
type: string
description: >-
Used by customers to specify the Purchase Order Number provided by
the buyer.
quantity:
type: number
description: The quantity of the product ordered.
related_subscription_number:
type: string
description: Use this field to relate an order line item to an subscription.
sold_to_id:
type: string
description: >-
The unique identifier of a contact belonging to the billing account
of the order line item. Use this field to assign and existing
contact as the sold to contact of an order line item.
example: 8ad0823f8040e52d0180433026b156fe
tax_code:
type: string
description: The tax code for the order line item.
unbilled_receivables_account:
type: string
description: An active accounting code in your Zuora chart of accounts..
state:
enum:
- pending
- booked
- sent_to_billing
- complete
- canceled
description: >-
The state of an order line item. If you want to generate billing
documents for order line items, you must set this field to
`sent_to_billing`. For invoice preview, you do not need to set this
field.
item_number:
type: string
description: >-
Human-readable identifier of the order item. It can be
user-supplied.
start_date:
type: string
format: date
description: >-
The date a transaction starts. The default value of this field is
the order date.
example: '2022-01-01'
end_date:
type: string
format: date
description: The date the order line item transitions to complete.
example: '2022-01-01'
price_id:
type: string
description: Identifier of the price.
quantity_available_for_return:
type: number
description: The quantity of the product ordered available for return.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items. EXPANDABLE
order_id:
type: string
description: >-
The unique identifier for the order associated with this order line
item.
total:
type: number
description: Total after discounts and taxes.
subtotal:
type: number
description: Total before discounts and taxes are applied.
quantity_fulfilled:
type: number
description: The quantity fulfilled.
quantity_pending_fulfillment:
type: number
description: The quantity pending fulfillment.
requires_fulfillment:
type: boolean
description: If true, a fulfillment is required to trigger billing.
original_order_date:
type: string
format: date
description: >-
The date when the subscription item is created through an order.
This field is to standardize the booking date information to
increase audit ability and traceability of data between Zuora
Billing and Zuora Revenue. It is mapped as the booking date for a
sales order line in Zuora Revenue.
example: '2022-01-01'
original_order_id:
type: string
description: >-
The unique identifier of the original sales order for a return order
line item.
original_order_line_item_id:
type: string
description: >-
The unique identifier of the original sales order line item for a
return order line item.
original_order_line_item_number:
type: string
description: >-
The number of the original sales order line item for a return order
line item.
original_order_number:
type: string
description: The number of the original sales order for a return order line item.
discount_total:
type: number
description: Total discount amount.
list_price:
type: number
description: >-
The extended list price for an order line item, calculated by the
formula: listPrice = listPricePerUnit * quantity
original_sold_to_id:
type: string
description: >-
The unique identifier of a contact belonging to the billing account
of the order line item that was the original sold to contact when
the order line item was created.
lineItemCreateRequest:
type: object
title: LineItemCreateRequest
description: Order line items
additionalProperties: false
properties:
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the original price with a per-unit price.
target_date:
type: string
format: date
description: >-
The target date for the order line item to be picked up by bill run
for billing.
custom_fields:
$ref: '#/components/schemas/customFields'
deferred_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
discount_unit_amount:
type: number
description: >-
Discount amount. Specify this field if you offer an amount-based
discount.
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
category:
type: string
enum:
- sale
- return
description: >-
The category for the order line item, to indicate a product sale or
return.
state:
type: string
enum:
- pending
- booked
- sent_to_billing
- complete
- canceled
description: >-
The state of an order line item. If you want to generate billing
documents for order line items, you must set this field to
`sent_to_billing`. For invoice preview, you do not need to set this
field.
type:
type: string
enum:
- product
- fee
- services
description: The type of the order line item.
name:
type: string
description: The name of the order line item.
item_number:
type: string
description: >-
Human-readable identifier of the order item. It can be
user-supplied.
list_unit_price:
type: number
description: The list price per unit for the order line item.
product_code:
type: string
description: The product code for the order line item.
price_id:
type: string
description: Identifier of the price.
purchase_order_number:
type: string
description: >-
Used by customers to specify the Purchase Order Number provided by
the buyer.
quantity:
type: number
description: >-
The quantity of units, such as the number of authors in a hosted
wiki service.
recognized_revenue_account:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
revenue_recognition_rule_name:
type: string
description: The revenue recognition rule for the order line item.
sold_to_id:
type: string
description: Customer address used for calculating tax.
example: 8ad0823f8040e52d0180433026b156fe
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
start_date:
type: string
format: date
description: >-
The date a transaction starts. The default value of this field is
the order date.
example: '2022-01-01'
end_date:
type: string
format: date
description: >-
The date a transaction is completed. The default value of this field
is the transaction start date. Also, the value of this field should
always equal or be later than the value of the `start_date` field.
example: '2022-01-01'
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items. EXPANDABLE
related_subscription_number:
type: string
description: >-
Relates an order line item to a subscription when you create the
order line item.
billing_rule:
type: string
enum:
- trigger_without_fulfillment
- trigger_on_fulfillment
description: The billing rule for the Order Line Item.
required:
- name
- type
lineItemListResponse:
type: object
title: LineItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/orderLineItem'
lineItemPatchRequest:
type: object
title: LineItemPatchRequest
description: Update an order line item
additionalProperties: false
properties:
revenue:
$ref: '#/components/schemas/orderLineItemRevenue'
unit_of_measure:
type: string
description: A configured unit of measure.
accounting_code:
type: string
description: An active accounting code in your Zuora chart of accounts.
adjustment_liability_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
unit_amount:
type: number
description: The unit amount to be charged.
target_date:
type: string
format: date
description: >-
All order line items that were unbilled on or before this date are
included in future bill runs.
billing_rule:
enum:
- trigger_without_fulfillment
- trigger_on_fulfillment
description: The billing rule for the order line item.
contract_asset_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
contract_liability_account:
type: string
description: An active accounting code in your Zuora chart of accounts.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
discount_unit_amount:
type: number
description: Discount amount per unit.
discount_percent:
type: number
description: Discount percent.
category:
enum:
- sale
- return
description: Category of the order line item.
name:
type: string
description: The name of the order line item.
type:
enum:
- product
- fee
- services
description: The type of the order line item.
list_unit_price:
type: number
description: The list price per unit for the order line item.
product_code:
type: string
description: The product code for the order line item.
purchase_order_number:
type: string
description: >-
Used by customers to specify the Purchase Order Number provided by
the buyer.
quantity:
type: number
description: The quantity of the product ordered.
related_subscription_number:
type: string
description: Use this field to relate an order line item to an subscription.
sold_to_id:
type: string
description: >-
The unique identifier of a contact belonging to the billing account
of the order line item. Use this field to assign and existing
contact as the sold to contact of an order line item.
example: 8ad0823f8040e52d0180433026b156fe
tax_code:
type: string
description: The tax code for the order line item.
unbilled_receivables_account:
type: string
description: An active accounting code in your Zuora chart of accounts..
state:
enum:
- pending
- booked
- sent_to_billing
- complete
- canceled
description: >-
The state of an order line item. If you want to generate billing
documents for order line items, you must set this field to
`sent_to_billing`. For invoice preview, you do not need to set this
field.
item_number:
type: string
description: >-
Human-readable identifier of the order item. It can be
user-supplied.
start_date:
type: string
format: date
description: >-
The date a transaction starts. The default value of this field is
the order date.
example: '2022-01-01'
end_date:
type: string
format: date
description: The date the order line item transitions to complete.
example: '2022-01-01'
orderCancellationRequest:
type: object
title: OrderCancellationRequest
description: ''
nullable: false
additionalProperties: false
properties:
cancel_reason:
type: string
description: The reason for cancelling the order.
ordersProcessingOption:
type: object
title: OrdersProcessingOption
description: Processing options for the invoice or payment.
additionalProperties: false
properties:
document_date:
type: string
format: date
description: The date printed on billing documents.
target_date:
type: string
format: date
description: >-
The target date for the order to be picked up by bill run for
billing.
collection_method:
type: string
enum:
- collect_payment
- create_invoice
- process_refund
- run_billing
description: >-
Specifies whether to just create an invoice, or to create an invoice
and collect payment.
payment_method_id:
type: string
description: Payment method Id used to pay billing documents.
payment_gateway_id:
type: string
description: >-
Identifier of the payment gateway Zuora will use to authorize the
payments that are made with this payment method.
example: 8ad093d07ae636bb017ae97518762aa3
draft_invoice:
type: boolean
refund_reason_code:
type: string
apply_credit:
type: boolean
description: >-
Whether to automatically apply credit memos or unapplied payments,
or both to an invoice.
ordersSchedulingOptions:
type: object
title: OrdersSchedulingOptions
description: ''
nullable: false
additionalProperties: false
properties:
scheduled_date:
type: string
format: date
description: The date when the order is scheduled to be processed.
orderListResponse:
type: object
title: OrderListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/order'
orderCreateRequest:
type: object
title: OrderCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
category:
type: string
enum:
- sale
- return
description: >-
Category of the order to indicate a product sale or return. Default
value is `sale`.
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
account_number:
type: string
description: Human-readable identifier of the account. It can be user-supplied.
example: A-100001
account_id:
type: string
description: Identifier of the account.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account_data:
allOf:
- $ref: '#/components/schemas/accountCreateRequest'
description: >-
The information of the new account that owns the subscription. The
subscription owner account can be different from the invoice owner
account. If you specify this field, do not specify `account_id`.
order_date:
type: string
format: date
description: >-
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if the
contract effective date field is skipped or its value is left as
null.
example: '2022-01-01'
order_number:
type: string
description: >-
The order number of the new order. If not provided, system will
auto-generate a number for this order. Note: Ensure that the
order number does not contain a slash.
line_items:
type: array
items:
$ref: '#/components/schemas/lineItemCreateRequest'
description: >-
Order line items are non-subscription-based items created by an
order, representing transactional charges such as one-time fees,
physical goods, or professional service charges that are not sold as
subscription services. By specifying this field, you can launch
non-subscription and unified monetization business models in Zuora,
in addition to subscription business models.
processing_options:
$ref: '#/components/schemas/ordersProcessingOption'
subscriptions:
type: array
items:
$ref: '#/components/schemas/postSubscriptionOrderRequest'
description: >-
Based on the intended order action, each item should include
specific fields. For example, to create a new subscription for a
new account, you must specify the `account_data` and
`subscription_plans` fields at a minimum.
scheduling_options:
$ref: '#/components/schemas/ordersSchedulingOptions'
state:
type: string
enum:
- pending
- complete
- draft
- canceled
- scheduled
- executing
- failed
description: The status of the order.
order:
type: object
title: Order
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
order_number:
type: string
description: >-
The order number of the new order. If not provided, system will
auto-generate a number for this order. Note: Ensure that the
order number does not contain a slash.
order_date:
type: string
format: date
description: >-
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if the
contract effective date field is skipped or its value is left as
null.
example: '2022-01-01'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
category:
type: string
enum:
- sale
- return
description: >-
Category of the order to indicate a product sale or return. Default
value is `sale`.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
line_items:
type: array
items:
$ref: '#/components/schemas/lineItemListResponse'
description: >-
Order line items are non-subscription-based items created by an
order, representing transactional charges such as one-time fees,
physical goods, or professional service charges that are not sold as
subscription services. By specifying this field, you can launch
non-subscription and unified monetization business models in Zuora,
in addition to subscription business models.
subscriptions:
type: array
items:
$ref: '#/components/schemas/postSubscriptionOrderResponse'
description: >-
Each item includes specific fields based on the intended order
action.
state:
type: string
enum:
- pending
- complete
- draft
- canceled
- scheduled
- executing
- failed
description: The status of the order.
scheduled_date:
type: string
format: date
description: The date when the order is scheduled to be processed.
scheduled_date_policy:
type: string
description: Date policy of the scheduled order.
subscriptionVersionOrder:
type: object
title: SubscriptionVersionOrder
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
order_number:
type: string
description: >-
The order number of the new order. If not provided, system will
auto-generate a number for this order. Note: Ensure that the
order number does not contain a slash.
order_date:
type: string
format: date
description: >-
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if the
contract effective date field is skipped or its value is left as
null.
example: '2022-01-01'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
category:
type: string
enum:
- sale
- return
description: >-
Category of the order to indicate a product sale or return. Default
value is `sale`.
line_items:
type: array
items:
$ref: '#/components/schemas/lineItemListResponse'
description: >-
Order line items are non-subscription-based items created by an
order, representing transactional charges such as one-time fees,
physical goods, or professional service charges that are not sold as
subscription services. By specifying this field, you can launch
non-subscription and unified monetization business models in Zuora,
in addition to subscription business models.
state:
type: string
enum:
- pending
- complete
- draft
- canceled
- scheduled
- executing
- failed
description: The status of the order.
actions:
allOf:
- $ref: '#/components/schemas/orderActionListResponse'
refundOrderTransactions:
type: object
title: RefundOrderTransactions
description: ''
nullable: false
additionalProperties: false
properties:
number:
type: string
description: The number of the refund.
invoice_numbers:
type: array
items:
type: string
description: The numbers of the related invoices.
state:
allOf:
- type: object
properties:
succeeded:
type: string
readOnly: true
failed:
type: string
readOnly: true
description: The states of the refunds.
refunds:
allOf:
- $ref: '#/components/schemas/refund'
description: The related invoices.
arTransactionsOrders:
type: object
title: ArTransactionsOrders
description: ''
nullable: false
additionalProperties: false
properties:
credit_memo_numbers:
type: array
items:
type: string
description: The numbers of related credit memos.
credit_memos:
allOf:
- $ref: '#/components/schemas/creditMemo'
description: The related credit memos.
invoice_numbers:
type: array
items:
type: string
description: The numbers of related invoices
invoices:
allOf:
- $ref: '#/components/schemas/invoice'
description: The related invoices.
refunds:
type: array
items:
$ref: '#/components/schemas/refundOrderTransactions'
description: The related refunds.
payments:
type: array
items:
$ref: '#/components/schemas/paymentTransactions'
description: The related payments.
orderCancelResponse:
type: object
title: OrderCancelResponse
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
order_number:
type: string
description: >-
The order number of the new order. If not provided, system will
auto-generate a number for this order. Note: Ensure that the
order number does not contain a slash.
order_date:
type: string
format: date
description: >-
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if the
contract effective date field is skipped or its value is left as
null.
example: '2022-01-01'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
category:
type: string
enum:
- sale
- return
description: >-
Category of the order to indicate a product sale or return. Default
value is `sale`.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
line_items:
type: array
items:
$ref: '#/components/schemas/lineItemListResponse'
description: >-
Order line items are non-subscription-based items created by an
order, representing transactional charges such as one-time fees,
physical goods, or professional service charges that are not sold as
subscription services. By specifying this field, you can launch
non-subscription and unified monetization business models in Zuora,
in addition to subscription business models.
subscriptions:
type: array
items:
$ref: '#/components/schemas/postSubscriptionOrderResponse'
description: >-
Each item includes specific fields based on the intended order
action.
state:
type: string
enum:
- pending
- complete
- draft
- canceled
- scheduled
- executing
- failed
description: The status of the order.
scheduled_date:
type: string
format: date
description: The date when the order is scheduled to be processed.
scheduled_date_policy:
type: string
description: Date policy of the scheduled order.
ar_transactions:
allOf:
- $ref: '#/components/schemas/arTransactionsOrders'
write_offs:
type: array
items:
$ref: '#/components/schemas/writeOff'
description: The billing documents that are written off.
lineItemsPreviewResponse:
type: object
title: LineItemsPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
mrr:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
tcb:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
tcv:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
orderPreviewCreateRequest:
type: object
title: OrderPreviewCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
category:
type: string
enum:
- sale
- return
description: >-
Category of the order to indicate a product sale or return. Default
value is `sale`.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
account_number:
type: string
description: Human-readable identifier of the account. It can be user-supplied.
example: A-100001
account_id:
type: string
description: Identifier of the account.
example: 2c92c0f86a8dd422016a9e7a70116b0d
order_date:
type: string
format: date
description: >-
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if the
contract effective date field is skipped or its value is left as
null.
example: '2022-01-01'
order_number:
type: string
description: >-
The order number of the new order. If not provided, system will
auto-generate a number for this order. Note: Ensure that the
order number does not contain a slash.
line_items:
type: array
items:
$ref: '#/components/schemas/lineItemCreateRequest'
description: >-
Order line items are non-subscription-based items created by an
order, representing transactional charges such as one-time fees,
physical goods, or professional service charges that are not sold as
subscription services. By specifying this field, you can launch
non-subscription and unified monetization business models in Zuora,
in addition to subscription business models.
subscriptions:
type: array
items:
$ref: '#/components/schemas/postSubscriptionOrderRequest'
description: >-
Based on the intended order action, each item should include
specific fields. For example, to preview a new subscription for
a new account, you must specify the `account_data` and
`subscription_plans` fields at a minimum.
account_data:
$ref: '#/components/schemas/subscriptionPreviewAccountRequest'
number_of_periods:
type: integer
description: Specifies how many billing periods you want to preview.
term_end:
type: boolean
description: >-
Indicates whether to preview the subscription till the end of the
current term.
metrics:
type: array
items:
type: string
enum:
- billing_documents
- delta_metrics
description: >-
Specifies the metrics you want to preview. You can preview
metrics of billing documents, the order delta metrics, or both.
end_date:
type: string
format: date
description: >-
End date of the period for which you want to preview the
subscription
required:
- metrics
tier:
type: object
title: Tier
description: Tier information for tiered prices.
additionalProperties: false
properties:
up_to:
type: number
description: >-
The upper bound of a tier. The lower bound of a tier is the upper
bound of the previous tier plus one or some fraction of one,
depending on the precision of the unit of measure.
amounts:
allOf:
- $ref: '#/components/schemas/money'
description: >-
Prices for the tier. Only set if `charge_model` is `tiered`,
`tiered_overage`, or `highwatermark_tiered`.
unit_amounts:
allOf:
- $ref: '#/components/schemas/money'
description: >-
Per unit prices for units in the tier. Only set if `charge_model` is
`tiered`, `tiered_overage`, or `highwatermark_tiered`.
itemTier:
type: object
title: ItemTier
description: Tiers information of the billing document items.
additionalProperties: false
properties:
up_to:
type: number
description: >-
Specifies the upper bound of the tier. The lower bound of a tier is
the upper bound of the previous tier plus one.
amount:
type: number
description: >-
The amount of the price. Specify this field if you want to override
the original price with a flat-fee price.
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the original price with a per-unit price.
overage:
type: object
title: Overage
description: An object defining how overage charges are calculated.
additionalProperties: false
properties:
interval_count:
type: integer
description: >-
Specifies the number of intervals used to calculate smoothed overage
charges.
type:
type: string
enum:
- rolling_window
- rollover
description: 'Represents the overage type: one of rolling_window or rollover.'
included_units:
type: number
description: Specifies the included units to which overage charges do not apply.
credit_unused_units:
type: boolean
description: Specifies whether or not to credit unused units.
apply_at_end_of_smoothing_period:
type: boolean
description: >-
Indicates if the overage price is calculated at the end of the
smoothing period.
revenue:
type: object
title: Revenue
description: Accounting configuration if you have Zuora Revenue enabled.
additionalProperties: false
properties:
exclude_item_billing_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated billing document items are excluded
from the revenue accounting.
exclude_item_booking_from_revenue_accounting:
type: boolean
description: >-
If set to `true`, any associated subscription items are excluded
from the revenue accounting.
recurring:
type: object
title: Recurring
description: The recurring components of a price such as interval and usage.
additionalProperties: false
properties:
recurring_on:
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
description: >-
Specifies on which day or the month or day of the week a customer
shall be billed.
'on':
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
deprecated: true
x-replaced-by: recurring_on
description: >-
Specifies on which day or the month or day of the week a customer
shall be billed.
usage:
type: boolean
description: Indicates that this is a usage price.
interval:
type: string
enum:
- month
- year
- week
- term
- day
description: Specifies the billing frequency. One of `week`, `month` or `year`.
interval_count:
type: integer
description: >-
The number of intervals (specified in the interval attribute)
between subscription billings. For example, interval=month and
intervalCount=3 bills every 3 months.
alignment_behavior:
type: string
enum:
- subscription_start
- term_start
- term_end
- none
description: >-
Specifies how to align billing for recurring (subscription) products
that start on different days.
timing:
type: string
enum:
- in_advance
- in_arrears
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based prices.
formula:
type: string
readOnly: true
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based prices.
duration_interval:
type: string
enum:
- day
- week
- month
- year
- subscription_term
- billing_period
description: Specifies the duration frequency. One of day, week, month or year.
duration_interval_count:
type: integer
description: >-
Specifies how long a customer shall be charged if this is less than
the duration of the subscription
rating_group:
type: string
enum:
- billing_period
- usage_start_date
- usage_record
- usage_upload
- custom_group
description: >-
A rating group based on which usage records are rated. Only
applicable to usage prices.
prepayment:
type: object
title: Prepayment
description: ''
nullable: false
additionalProperties: false
properties:
credit_option:
type: string
enum:
- time_based
- consumption_based
- full_credit
description: >-
The way to calculate credit. See <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_with_Drawdown/A_Create_prepayment_charge#Credit_Option'
target='_blank'>Credit Option</a> for more information.
quantity:
type: number
description: The number of units included in a prepayment charge.
total_quantity:
type: number
description: >-
The total amount of units that end customers can use during a
validity period when they subscribe to a prepayment charge.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
validity_period:
type: string
enum:
- subscription_term
- annual
- semi_annual
- quarter
- month
description: >-
The period in which the prepayment units are valid to use as defined
in a prepayment charge.
drawdown:
type: object
title: Drawdown
description: ''
nullable: false
additionalProperties: false
properties:
conversion_rate:
type: number
description: >-
The conversion rate between usage unit of measure (UOM) and drawdown
unit of measure for a drawdown charge. **Note**: <ul>
<li>Must be a positive number (>0).</li> <li>Must be `1` when
usage UOM and drawdown UOM are the same.</li> <li>If both
`conversion_rate` and `unit_of_measure` for the drawdown are empty,
the system will set default values respectively: <ul> <li>
`conversion_rate`: 1 </li> <li> `unit_of_measure`: Same as the
usage UOM of this drawdown charge. </li></ul></li></ul> The
`conversion_rate` and `unit_of_measure` fields need to have values
or be empty at the same time.
unit_of_measure:
type: string
description: Unit of measurement for a drawdown charge.
price:
type: object
title: Price
description: Price information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
name:
type: string
description: The name of the price.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
recognized_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recurring:
type: object
title: Recurring
description: The recurring components of a price such as interval and usage.
additionalProperties: false
properties:
recurring_on:
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
'on':
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
deprecated: true
x-replaced-by: recurring_on
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
usage:
type: boolean
description: Indicates that this is a usage price.
interval:
type: string
enum:
- month
- year
- week
- term
- day
description: >-
Specifies the billing frequency. One of `week`, `month` or
`year`.
interval_count:
type: integer
description: >-
The number of intervals (specified in the interval attribute)
between subscription billings. For example, interval=month and
intervalCount=3 bills every 3 months.
alignment_behavior:
type: string
enum:
- subscription_start
- term_start
- term_end
- none
description: >-
Specifies how to align billing for recurring (subscription)
products that start on different days.
timing:
type: string
enum:
- in_advance
- in_arrears
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based
prices.
formula:
type: string
readOnly: true
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based
prices.
duration_interval:
type: string
enum:
- day
- week
- month
- year
- subscription_term
- billing_period
description: >-
Specifies the duration frequency. One of day, week, month or
year.
duration_interval_count:
type: integer
description: >-
Specifies how long a customer shall be charged if this is less
than the duration of the subscription
rating_group:
type: string
enum:
- billing_period
- usage_start_date
- usage_record
- usage_upload
- custom_group
description: >-
A rating group based on which usage records are rated. Only
applicable to usage prices.
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
deprecated: true
description: Specifies the mode for tiered prices.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one_time, recurring and plan.
tiers:
type: array
items:
$ref: '#/components/schemas/tier'
description: >-
Price information for different tiers. When creating or updating
tiered prices, you must specify this field and the `tiers_mode`
field.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
min_quantity:
type: number
description: >-
The minimum quantity for a price. Specify this field and the
`max_quantity` field to create a range of quantities allowed in a
price.
max_quantity:
type: number
description: >-
The maximum quantity for a price. Specify this field and the
`min_quantity` field to create a range of quantities allowed in a
price.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: account,
subscription, or plan.
revenue_recognition_rule:
type: string
enum:
- on_invoice
- daily_over_time
description: >-
Determines when to recognize the revenue for this charge. You can
choose to recognize upon invoicing or daily over time.
stacked_discount:
type: boolean
description: >-
This field is only applicable for the Percentage Discount price.
This field indicates whether the discount is to be calculated as
stacked discount. Possible values are as follows: <ul>
<li>`true`: This is a stacked discount, which should be calculated
by stacking with other discounts.</li> <li> `false`: This is
not a stacked discount, which should be calculated in sequence with
other discounts.</li></ul> For more information, see <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models'
target='_blank'>Stacked discounts</a>
amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
unit_amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
discount_amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
description: >-
Specifies the base interval of a price. If not provided, this field
defaults to `billing_period`.
overage:
allOf:
- $ref: '#/components/schemas/overage'
deprecated: true
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
accounting_code:
type: string
description: >-
An active accounting code defined in **Finance Settings > Configure
Accounting Codes** in your Zuora tenant.
prepayment:
type: object
title: Prepayment
description: ''
nullable: false
additionalProperties: false
properties:
credit_option:
type: string
enum:
- time_based
- consumption_based
- full_credit
description: >-
The way to calculate credit. See <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_with_Drawdown/A_Create_prepayment_charge#Credit_Option'
target='_blank'>Credit Option</a> for more information.
quantity:
type: number
description: The number of units included in a prepayment charge.
total_quantity:
type: number
description: >-
The total amount of units that end customers can use during a
validity period when they subscribe to a prepayment charge.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for
per-unit prices.
validity_period:
type: string
enum:
- subscription_term
- annual
- semi_annual
- quarter
- month
description: >-
The period in which the prepayment units are valid to use as
defined in a prepayment charge.
drawdown:
type: object
title: Drawdown
description: ''
nullable: false
additionalProperties: false
properties:
conversion_rate:
type: number
description: >-
The conversion rate between usage unit of measure (UOM) and
drawdown unit of measure for a drawdown charge.
**Note**: <ul> <li>Must be a positive number (>0).</li>
<li>Must be `1` when usage UOM and drawdown UOM are the
same.</li> <li>If both `conversion_rate` and
`unit_of_measure` for the drawdown are empty, the system will
set default values respectively: <ul> <li>
`conversion_rate`: 1 </li> <li> `unit_of_measure`: Same as
the usage UOM of this drawdown charge.
</li></ul></li></ul> The `conversion_rate` and
`unit_of_measure` fields need to have values or be empty at the
same time.
unit_of_measure:
type: string
description: Unit of measurement for a drawdown charge.
taxable:
type: boolean
price_change_percentage:
type: number
description: >-
The percentage to increase or decrease the price of a termed
subscription's renewal.
price_change_option:
type: string
enum:
- latest_catalog_pricing
- percentage
- none
default: none
description: >-
Applies an automatic price change when a termed subscription is
renewed.
price_increase_option:
type: boolean
description: >-
Indicates whether to apply an automatic price change when a termed
subscription is renewed.
plan_id:
type: string
description: Specify the ID of a plan to which this price is associated.
plan_number:
type: string
description: >-
Specify the number of a plan to which this price is associated. This
field is required if plan_id is not supplied
custom_field_per_unit_rate:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a per unit rate
under the `Pre-Rated Per Unit` charge model
custom_field_total_amount:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a total amount
under the `Pre-Rated` charge model
active:
type: boolean
deprecated: true
description: Whether the price can be used for new purchases.
charge_type:
type: string
description: The type of charge. Can be `one_time`,`recurring`, or `usage`.
charge_model:
type: string
description: >-
The charge model of the price, which determines how users are
charged. Common charge models include flat fee, per-unit, volume,
and tiered prices.
priceListResponse:
type: object
title: PriceListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/price'
pricePatchRequest:
type: object
title: PricePatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
name:
type: string
description: The name of the price.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
recognized_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recurring:
$ref: '#/components/schemas/recurring'
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
deprecated: true
description: Specifies the mode for tiered prices.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one_time, recurring and plan.
tiers:
type: array
items:
$ref: '#/components/schemas/tier'
description: >-
Price information for different tiers. When creating or updating
tiered prices, you must specify this field and the `tiers_mode`
field.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
min_quantity:
type: number
description: >-
The minimum quantity for a price. Specify this field and the
`max_quantity` field to create a range of quantities allowed in a
price.
max_quantity:
type: number
description: >-
The maximum quantity for a price. Specify this field and the
`min_quantity` field to create a range of quantities allowed in a
price.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: account,
subscription, or plan.
revenue_recognition_rule:
type: string
enum:
- on_invoice
- daily_over_time
description: >-
Determines when to recognize the revenue for this charge. You can
choose to recognize upon invoicing or daily over time.
stacked_discount:
type: boolean
description: >-
This field is only applicable for the Percentage Discount price.
This field indicates whether the discount is to be calculated as
stacked discount. Possible values are as follows: <ul>
<li>`true`: This is a stacked discount, which should be calculated
by stacking with other discounts.</li> <li> `false`: This is
not a stacked discount, which should be calculated in sequence with
other discounts.</li></ul> For more information, see <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models'
target='_blank'>Stacked discounts</a>
amounts:
$ref: '#/components/schemas/money'
unit_amounts:
$ref: '#/components/schemas/money'
discount_amounts:
$ref: '#/components/schemas/money'
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
description: >-
Specifies the base interval of a price. If not provided, this field
defaults to `billing_period`.
overage:
allOf:
- $ref: '#/components/schemas/overage'
deprecated: true
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
accounting_code:
type: string
description: >-
An active accounting code defined in **Finance Settings > Configure
Accounting Codes** in your Zuora tenant.
prepayment:
$ref: '#/components/schemas/prepayment'
drawdown:
$ref: '#/components/schemas/drawdown'
taxable:
type: boolean
price_change_percentage:
type: number
description: >-
The percentage to increase or decrease the price of a termed
subscription's renewal.
price_change_option:
type: string
enum:
- latest_catalog_pricing
- percentage
- none
default: none
description: >-
Applies an automatic price change when a termed subscription is
renewed.
price_increase_option:
type: boolean
description: >-
Indicates whether to apply an automatic price change when a termed
subscription is renewed.
product:
type: object
title: Product
description: Product information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the product can be used for new purchases.
end_date:
type: string
format: date
description: >-
The date on which the product can no longer be used for new
purchases.
name:
type: string
description: The name of the product.
type:
type: string
enum:
- base
- add_on
- other
description: The type of product.
sku:
type: string
description: The sku identifier of the product.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
active:
type: boolean
description: Whether the product can be used for new purchases.
plans:
allOf:
- $ref: '#/components/schemas/planListResponse'
readOnly: true
description: A list of plans.
productListResponse:
type: object
title: ProductListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/product'
priceCreateRequest:
type: object
title: PriceCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
name:
type: string
description: The name of the price.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
recognized_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recurring:
$ref: '#/components/schemas/recurring'
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
default: contract_effective
description: Specifies when to start billing your customer.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
deprecated: true
description: Specifies the mode for tiered prices.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one_time, recurring and plan.
tiers:
type: array
items:
$ref: '#/components/schemas/tier'
description: >-
Price information for different tiers. When creating or updating
tiered prices, you must specify this field and the `tiers_mode`
field.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
min_quantity:
type: number
description: >-
The minimum quantity for a price. Specify this field and the
`max_quantity` field to create a range of quantities allowed in a
price.
max_quantity:
type: number
description: >-
The maximum quantity for a price. Specify this field and the
`min_quantity` field to create a range of quantities allowed in a
price.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: account,
subscription, or plan.
revenue_recognition_rule:
type: string
enum:
- on_invoice
- daily_over_time
description: >-
Determines when to recognize the revenue for this charge. You can
choose to recognize upon invoicing or daily over time.
stacked_discount:
type: boolean
description: >-
This field is only applicable for the Percentage Discount price.
This field indicates whether the discount is to be calculated as
stacked discount. Possible values are as follows: <ul>
<li>`true`: This is a stacked discount, which should be calculated
by stacking with other discounts.</li> <li> `false`: This is
not a stacked discount, which should be calculated in sequence with
other discounts.</li></ul> For more information, see <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models'
target='_blank'>Stacked discounts</a>
amounts:
$ref: '#/components/schemas/money'
unit_amounts:
$ref: '#/components/schemas/money'
discount_amounts:
$ref: '#/components/schemas/money'
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
default: billing_period
description: >-
Specifies the base interval of a price. If not provided, this field
defaults to `billing_period`.
overage:
allOf:
- $ref: '#/components/schemas/overage'
deprecated: true
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
accounting_code:
type: string
description: >-
An active accounting code defined in **Finance Settings > Configure
Accounting Codes** in your Zuora tenant.
prepayment:
$ref: '#/components/schemas/prepayment'
drawdown:
$ref: '#/components/schemas/drawdown'
taxable:
type: boolean
price_change_percentage:
type: number
description: >-
The percentage to increase or decrease the price of a termed
subscription's renewal.
price_change_option:
type: string
enum:
- latest_catalog_pricing
- percentage
- none
default: none
description: >-
Applies an automatic price change when a termed subscription is
renewed.
price_increase_option:
type: boolean
description: >-
Indicates whether to apply an automatic price change when a termed
subscription is renewed.
plan_id:
type: string
description: Specify the ID of a plan to which this price is associated.
plan_number:
type: string
description: >-
Specify the number of a plan to which this price is associated. This
field is required if plan_id is not supplied
custom_field_per_unit_rate:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a per unit rate
under the `Pre-Rated Per Unit` charge model
custom_field_total_amount:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a total amount
under the `Pre-Rated` charge model
required:
- name
planPatchRequest:
type: object
title: PlanPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the plan can be used for new purchases.
end_date:
type: string
format: date
description: The date on which the plan can no longer be used for new purchases.
name:
type: string
description: The name of the plan.
plan_number:
type: string
description: Human-readable identifier of the plan. It can be user-supplied.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
active_currencies:
type: array
items:
type: string
description: >-
A list of 3-letter ISO-standard currency codes representing active
currencies for the plan.
plan:
type: object
title: Plan
description: Plan information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the plan can be used for new purchases.
end_date:
type: string
format: date
description: The date on which the plan can no longer be used for new purchases.
name:
type: string
description: The name of the plan.
plan_number:
type: string
description: Human-readable identifier of the plan. It can be user-supplied.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
active_currencies:
type: array
items:
type: string
description: >-
A list of 3-letter ISO-standard currency codes representing active
currencies for the plan.
product_id:
type: string
description: Identifier of the product associated with this plan.
active:
type: boolean
description: Whether the plan can be used for new purchases.
product:
allOf:
- $ref: '#/components/schemas/product'
description: The product associated with this plan.
sku:
type: string
description: >-
The product sku. This field is only availble for customers using
high speed cache.
prices:
allOf:
- $ref: '#/components/schemas/priceListResponse'
readOnly: true
description: A list of prices.
planListResponse:
type: object
title: PlanListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/plan'
planCreateRequest:
type: object
title: PlanCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the plan can be used for new purchases.
end_date:
type: string
format: date
description: The date on which the plan can no longer be used for new purchases.
name:
type: string
description: The name of the plan.
plan_number:
type: string
description: Human-readable identifier of the plan. It can be user-supplied.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
active_currencies:
type: array
items:
type: string
description: >-
A list of 3-letter ISO-standard currency codes representing active
currencies for the plan.
product_id:
type: string
description: Identifier of the product associated with this plan.
required:
- product_id
- name
productPatchRequest:
type: object
title: ProductPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the product can be used for new purchases.
end_date:
type: string
format: date
description: >-
The date on which the product can no longer be used for new
purchases.
name:
type: string
description: The name of the product.
type:
type: string
enum:
- base
- add_on
- other
description: The type of product.
sku:
type: string
description: The sku identifier of the product.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
productCreateRequest:
type: object
title: ProductCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
start_date:
type: string
format: date
description: The date from which the product can be used for new purchases.
end_date:
type: string
format: date
description: >-
The date on which the product can no longer be used for new
purchases.
name:
type: string
description: The name of the product.
type:
type: string
enum:
- base
- add_on
- other
description: The type of product.
sku:
type: string
description: The sku identifier of the product.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
required:
- name
billingDocument:
type: object
title: BillingDocument
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: Identifier of the account that owns the billing document.
account_number:
type: string
description: >-
Human-readable identifier of the account that owns the billing
document.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the billing document is due.
example: '2023-01-01'
document_date:
type: string
format: date
description: The date when the billing document takes effect.
example: '2023-01-01'
reason_code:
type: string
description: >-
Reason for issuing this billing document. This field is applicable
only if the `type` field is set to `credit_memo` or `debit_memo`.
invoice_id:
type: string
description: >-
The identifier of the invoice billing document from which this
credit memo or debit memo billing document is created. This field is
applicable only if the `type` field is set to `credit_memo` or
`debit_memo`.
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo billing document from
the rule of automatically applying it to invoices. This field is
applicable only if the `type` field is set to `credit_memo`.
pay:
type: boolean
description: >-
Indicates whether the billing document is automatically picked up
for processing in the corresponding payment run.
type:
type: string
enum:
- credit_memo
- debit_memo
- invoice
description: >-
The type of billing document. Can be one of the credit memo, debit
memo, or invoice.
billing_document_number:
type: string
readOnly: true
description: >-
A human-readable identifier for the billing document; may be
user-supplied.
amount_refunded:
type: number
description: The amount of this billing document item refunded.
state_transitions:
allOf:
- type: object
properties:
posted_time:
type: string
readOnly: true
canceled_time:
type: string
readOnly: true
posted_by_id:
type: string
readOnly: true
description: Identifier of the Zuora user who posted the billing document.
state:
type: string
enum:
- draft
- open
- uncollectible
- failed
description: The status of the billing document.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the billing document. EXPANDABLE
items:
allOf:
- $ref: '#/components/schemas/billingDocumentItemListResponse'
readOnly: true
description: List of billing document items.
total:
type: number
readOnly: true
description: The total amount.
subtotal:
type: number
readOnly: true
description: The total amount exclusive of tax.
tax:
type: number
readOnly: true
description: The total tax amount.
balance:
type: number
readOnly: true
deprecated: true
description: >-
The total balance remaining. This field is deprecated. Use
`remaining_balance` field.
remaining_balance:
type: number
readOnly: true
description: The total balance remaining.
amount_paid:
type: number
readOnly: true
description: The total amount paid.
paid:
type: boolean
readOnly: true
description: >-
Whether payment was successfully collected for this invoice. An
invoice can be paid with a payment or a credit memo.
past_due:
type: boolean
readOnly: true
description: Whether payment is past due.
billingDocumentListResponse:
type: object
title: BillingDocumentListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/billingDocument'
billingDocumentCreateRequest:
type: object
title: BillingDocumentCreateRequest
description: ''
additionalProperties: false
properties:
account_id:
type: string
description: Identifier of the account that owns the billing document.
account_number:
type: string
description: >-
Human-readable identifier of the account that owns the billing
document.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the billing document is due.
example: '2022-01-01'
document_date:
type: string
format: date
description: The date when the billing document takes effect.
example: '2023-01-01'
reason_code:
type: string
description: >-
Reason for issuing this billing document. This field is applicable
only if the `type` field is set to `credit_memo` or `debit_memo`.
invoice_id:
type: string
description: >-
The identifier of the invoice billing document from which this
credit memo or debit memo billing document is created. This field is
applicable only if the `type` field is set to `credit_memo` or
`debit_memo`.
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
custom_fields:
$ref: '#/components/schemas/customFields'
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo billing document from
the rule of automatically applying it to invoices. This field is
applicable only if the `type` field is set to `credit_memo`.
pay:
type: boolean
description: >-
Indicates whether the billing document is automatically picked up
for processing in the corresponding payment run.
type:
type: string
enum:
- credit_memo
- debit_memo
- invoice
description: >-
The type of billing document. Can be one of the credit memo, debit
memo, or invoice.
items:
type: array
items:
$ref: '#/components/schemas/billingDocumentItemCreateRequest'
description: Information of all billing document items.
apply:
type: boolean
description: Whether to automatically apply the billing document upon posting.
post:
type: boolean
description: >-
Whether to automatically post a billing document after it is
created.
required:
- type
billingDocumentItemPaymentApplicationRequest:
type: object
title: BillingDocumentItemPaymentApplicationRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Identifier of an invoice item or a debit memo item.
amount:
type: number
description: The amount applied to this billing document item or taxation item.
taxation_item_id:
type: string
description: The identifier of a taxation item.
required:
- id
- amount
billingDocumentPaymentApplicationRequest:
type: object
title: BillingDocumentPaymentApplicationRequest
description: ''
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the billing document to which the credit memo,
payment, or refund is applied.
type:
type: string
enum:
- debit_memo
- invoice
description: The type of billing document.
amount:
type: number
description: The amount applied to this billing document.
billing_document_number:
type: string
readOnly: true
description: >-
A human-readable identifier for the billing document; may be
user-supplied.
items:
type: array
items:
$ref: '#/components/schemas/billingDocumentItemPaymentApplicationRequest'
description: >-
The billing document items (invoice items or debit memo items or
taxation items) to which the payment is applied.
required:
- type
- id
- amount
invoice:
type: object
title: Invoice
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: Identifier of the account that owns the invoice.
account_number:
type: string
description: Human-readable identifier of the account that owns the invoice.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the invoice is due.
example: '2023-01-01'
document_date:
type: string
format: date
description: The date when the invoice takes effect.
example: '2023-01-01'
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
pay:
type: boolean
description: >-
Indicates whether the invoice is automatically picked up for
processing in the corresponding payment run.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
invoice_number:
type: string
readOnly: true
description: A human-readable identifier for the invoice; may be user-supplied.
state_transitions:
allOf:
- type: object
properties:
posted_time:
type: string
readOnly: true
canceled_time:
type: string
readOnly: true
posted_by_id:
type: string
readOnly: true
description: Identifier of the Zuora user who posted the invoice.
state:
type: string
enum:
- draft
- posted
- open
- canceled
- failed
description: The status of the invoice.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the invoice. EXPANDABLE
items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items.
total:
type: number
readOnly: true
description: The total amount.
subtotal:
type: number
readOnly: true
description: The total amount exclusive of tax.
tax:
type: number
readOnly: true
description: The total tax amount.
balance:
type: number
readOnly: true
deprecated: true
description: >-
The total balance remaining. This field is deprecated. Use
`remaining_balance` field.
remaining_balance:
type: number
readOnly: true
description: The total balance remaining.
paid:
type: boolean
readOnly: true
description: >-
Whether payment was successfully collected for this invoice. An
invoice can be paid with a payment or a credit memo.
past_due:
type: boolean
readOnly: true
description: Whether payment is past due.
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
flexibleBillingDocumentSettings:
type: object
title: FlexibleBillingDocumentSettings
description: ''
nullable: false
additionalProperties: false
properties:
template_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: >-
Identifier of the invoice template associated with this customer.
Not applicable for debit memos or credit memos.
example: 2c92c08b6a8c978f016a9e0084622b62
sequence_set_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the billing document sequence set.
invoiceListResponse:
type: object
title: InvoiceListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/invoice'
invoiceCreateRequest:
type: object
title: InvoiceCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
account_id:
type: string
description: Identifier of the account that owns the invoice.
account_number:
type: string
description: Human-readable identifier of the account that owns the invoice.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the invoice is due.
example: '2022-01-01'
document_date:
type: string
format: date
description: The date when the invoice takes effect.
example: '2023-01-01'
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
custom_fields:
$ref: '#/components/schemas/customFields'
pay:
type: boolean
description: >-
Indicates whether the invoice is automatically picked up for
processing in the corresponding payment run.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
items:
type: array
items:
$ref: '#/components/schemas/invoiceItemCreateRequest'
description: Information of all invoice items.
post:
type: boolean
description: Whether to automatically post an invoice after it is created.
invoicePatchRequest:
type: object
title: InvoicePatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
pay:
type: boolean
description: >-
Indicates whether the billing document is automatically picked up
for processing in the corresponding payment run.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the billing document is due.
example: '2022-01-01'
document_date:
type: string
format: date
description: The date when the billing document takes effect.
example: '2023-01-01'
custom_fields:
$ref: '#/components/schemas/customFields'
invoiceReverseRequest:
type: object
title: InvoiceReverseRequest
description: ''
nullable: false
additionalProperties: false
properties:
document_date:
type: string
format: date
description: The date that appears on the credit memo.
example: '2023-01-01'
apply_date:
type: string
format: date
example: '2023-01-01'
invoiceItemCreateRequest:
type: object
title: InvoiceItemCreateRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: >-
Amount (in the currency specified) of the invoice item. This should
always be equal to unit_amount * quantity.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
recognized_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
format: date
description: >-
The end date of the service period associated with this invoice
item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
service_start:
type: string
format: date
description: >-
The start date of the service period associated with this invoice
item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
tax_inclusive:
type: boolean
description: >-
Indicates whether the invoice item amount is inclusive or exclusive
of tax.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
taxation_items:
type: array
items:
$ref: '#/components/schemas/taxationItemCreateRequest'
description: List of taxation items.
unit_amount:
type: number
description: Unit amount (in the currency specified) of the invoice item.
booking_reference:
type: string
description: The booking reference for this invoice item.
price_id:
type: string
description: The identifier of the price this invoice item is associated with.
purchase_order_number:
type: string
description: The purchase order number associated with this invoice item.
tax_code:
type: string
description: The designated tax code.
document_item_date:
type: string
format: date-time
description: The date when the invoice item takes effect
example: '2023-12-19T14:52:28-06:00'
name:
type: string
description: >-
Name of the invoice item displayed to customers on billing
documents.
accounting_code:
type: string
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- service_start
- amount
payInvoiceRequest:
type: object
title: PayInvoiceRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: The amount of the payment.
account_id:
type: string
description: >-
Identifier of the account that owns the invoice. Either `account_id`
or `account_number` is required.
account_number:
type: string
description: >-
Human-readable identifier of the account that owns the invoice.
Either `account_number` or `account_id` is required.
authorization_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
currency:
type: string
description: 3-letter ISO 4217 currency code.
bank_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
payment_date:
type: string
format: date
description: The date and time when the payment takes effect.
payment_method_id:
type: string
description: Identifier of the payment method used to create this payment.
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
this payment.
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
payment gateway when a payment is created. If not specified, the
payment number will be passed in instead.
reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this payment is not handled by Zuora.
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- currency
invoiceItem:
type: object
title: InvoiceItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
amount:
type: number
description: The total amount of this invoice item.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: >-
The accounting code for the deferred revenue, such as Monthly
Recurring Liability.
recognized_revenue_account:
type: string
description: >-
The accounting code for the recognized revenue, such as Monthly
Recurring Charges or Overage Charges.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
description: >-
The end date of the service period associated with this invoice
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
accounts_receivable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
discount_item:
type: boolean
description: If true, indicates that the item is a discount item.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item or a debit memo item that this
discount item or credit memo item is applied to.
service_start:
type: string
description: >-
The start date of the service period associated with this invoice
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
accounting_code:
type: string
invoice_id:
type: string
description: The identifier of the invoice associated with this invoice item.
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
subscription_id:
type: string
description: The identifier of the subscription associated with the invoice item.
tax_inclusive:
type: boolean
description: >-
This specifies if the invoice item amount is inclusive or exclusive
of tax.
remaining_balance:
type: number
description: The remaining balance of this invoice item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
unit_amount:
type: number
description: Unit amount (in the currency specified) of the invoice item.
booking_reference:
type: string
description: The booking reference for this invoice item.
name:
type: string
description: >-
Name of the invoice item displayed to customers on billing
documents.
document_item_date:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the invoice item was created in ISO 8601 UTC
format.
price_id:
type: string
description: The identifier of the price this invoice item is associated with.
purchase_order_number:
type: string
description: The purchase order number associated with this invoice item.
tax:
type: number
description: The amount of tax applied to the invoice item.
tax_code:
type: string
description: The designated tax code.
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this invoice
item.
taxation_items:
type: object
title: TaxationItemListResponse
description: Information of the taxation items.
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/taxationItem'
invoice:
allOf:
- $ref: '#/components/schemas/invoice'
description: The invoice the item belongs to. EXPANDABLE
line_item:
allOf:
- $ref: '#/components/schemas/lineItem'
description: The order line item associated with this invoice item. EXPANDABLE
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
readOnly: true
description: List of customer subscriptions.
subscription_item:
allOf:
- $ref: '#/components/schemas/subscriptionItem'
description: >-
The expandable subscription item associated with this billing
document item.
invoiceItemListResponse:
type: object
title: InvoiceItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/invoiceItem'
writeOffItemsRequest:
type: object
title: WriteOffItemsRequest
description: ''
nullable: false
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
recognized_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
service_end:
type: string
format: date
description: >-
The end date of the service period associated with this invoice
item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
service_start:
type: string
format: date
description: >-
The start date of the service period associated with this invoice
item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
id:
type: string
description: The unique identifier of the invoice item.
custom_fields:
$ref: '#/components/schemas/customFields'
writeOffRequest:
type: object
title: WriteOffRequest
description: ''
nullable: false
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
document_date:
type: string
format: date
description: The date when the invoice takes effect.
example: '2023-01-01'
reason_code:
type: string
description: Reason for issuing this credit memo
custom_fields:
$ref: '#/components/schemas/customFields'
invoice_items:
type: array
items:
$ref: '#/components/schemas/writeOffItemsRequest'
description: Information of all invoice items.
debitMemo:
type: object
title: DebitMemo
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: Identifier of the account that owns the debit memo.
account_number:
type: string
description: Human-readable identifier of the account that owns the debit memo.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the billing document is due.
example: '2023-01-01'
document_date:
type: string
format: date
description: The date when the debit memo takes effect.
example: '2023-01-01'
reason_code:
type: string
description: >-
Reason for issuing this debit memo. This field is applicable only if
the `type` field is set to `credit_memo` or `debit_memo`.
invoice_id:
type: string
description: >-
The identifier of the invoice from which this credit memo or debit
memo is created. This field is applicable only if the `type` field
is set to `credit_memo` or `debit_memo`.
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo from the rule of
automatically applying it to invoices. This field is applicable only
if the `type` field is set to `credit_memo`.
pay:
type: boolean
description: >-
Indicates whether this billing document is automatically picked up
for processing in the corresponding payment run.
currency:
type: string
description: 3-letter ISO 4217 currency code
debit_memo_number:
type: string
readOnly: true
description: >-
A human-readable identifier for the billing document; may be
user-supplied.
amount_refunded:
type: number
description: The amount of this billing document item refunded.
state_transitions:
allOf:
- type: object
properties:
posted_time:
type: string
readOnly: true
canceled_time:
type: string
readOnly: true
posted_by_id:
type: string
readOnly: true
description: Identifier of the Zuora user who posted the debit memo.
state:
type: string
enum:
- draft
- posted
- open
- canceled
- failed
description: The status of the debit memo.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the billing document. EXPANDABLE
items:
allOf:
- $ref: '#/components/schemas/billingDocumentItemListResponse'
readOnly: true
description: List of debit memo items.
total:
type: number
readOnly: true
description: The total amount.
subtotal:
type: number
readOnly: true
description: The total amount exclusive of tax.
tax:
type: number
readOnly: true
description: The total tax amount.
balance:
type: number
readOnly: true
deprecated: true
description: >-
The total balance remaining. This field is deprecated. Use
`remaining_balance` field.
remaining_balance:
type: number
readOnly: true
description: The total balance remaining.
amount_paid:
type: number
readOnly: true
description: The total amount paid.
paid:
type: boolean
readOnly: true
description: >-
Whether payment was successfully collected for this invoice. An
invoice can be paid with a payment or a credit memo.
past_due:
type: boolean
readOnly: true
description: Whether payment is past due.
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
debitMemoListResponse:
type: object
title: DebitMemoListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/debitMemo'
debitMemoCreateRequest:
type: object
title: DebitMemoCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
account_id:
type: string
description: Identifier of the account that owns the debit memo.
account_number:
type: string
description: Human-readable identifier of the account that owns the debit memo.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the debit memo is due.
example: '2022-01-01'
document_date:
type: string
format: date
description: The date when the debit memo takes effect.
example: '2023-01-01'
reason_code:
type: string
description: >-
Reason for issuing this debit memo. This field is applicable only if
the `type` field is set to `credit_memo` or `debit_memo`.
invoice_id:
type: string
description: >-
The identifier of the invoice from which this credit memo or debit
memo is created. This field is applicable only if the `type` field
is set to `credit_memo` or `debit_memo`.
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
custom_fields:
$ref: '#/components/schemas/customFields'
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo from the rule of
automatically applying it to invoices. This field is applicable only
if the `type` field is set to `credit_memo`.
pay:
type: boolean
description: >-
Indicates whether this billing document is automatically picked up
for processing in the corresponding payment run.
currency:
type: string
description: 3-letter ISO 4217 currency code
items:
type: array
items:
$ref: '#/components/schemas/billingDocumentItemCreateRequest'
description: Information of all billing document items.
apply:
type: boolean
description: Whether to automatically apply the billing document upon posting.
post:
type: boolean
description: >-
Whether to automatically post a billing document after it is
created.
debitMemoPatchRequest:
type: object
title: DebitMemoPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
pay:
type: boolean
description: >-
Indicates whether the billing document is automatically picked up
for processing in the corresponding payment run.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
due_date:
type: string
format: date
description: The date on which payment for the billing document is due.
example: '2022-01-01'
document_date:
type: string
format: date
description: The date when the billing document takes effect.
example: '2023-01-01'
reason_code:
type: string
description: >-
Reason for issuing this billing document. This field is applicable
only if the `type` field is set to `credit_memo` or `debit_memo`.
custom_fields:
$ref: '#/components/schemas/customFields'
debitMemoItem:
type: object
title: DebitMemoItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
amount:
type: number
description: The total amount of this debit memo item.
subtotal:
type: number
description: The total amount of this debit memo item exclusive of tax.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: >-
The accounting code for the deferred revenue, such as Monthly
Recurring Liability.
on_account_account:
type: string
description: >-
The accounting code that maps to an on account in your accounting
system.
recognized_revenue_account:
type: string
description: >-
The accounting code for the recognized revenue, such as Monthly
Recurring Charges or Overage Charges.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
description: >-
The end date of the service period associated with this debit memo
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
service_start:
type: string
description: >-
The start date of the service period associated with this debit memo
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
accounts_receivable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
discount_item:
type: boolean
description: If true, indicates that the item is a discount item.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item that this debit memo item is applied
to.
accounting_code:
type: string
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
tax_inclusive:
type: boolean
description: >-
This specifies if the debit memo item amount is inclusive or
exclusive of tax.
remaining_balance:
type: number
description: The remaining balance of this debit memo item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
unit_amount:
type: number
description: Unit amount of the debit memo item.
name:
type: string
description: >-
Name of the billing document item displayed to customers on the
billing document.
price_id:
type: string
description: The identifier of the price this debit memo item is associated with.
purchase_order_number:
type: string
description: The purchase order number associated with this debit memo item.
tax:
type: number
description: The amount of tax applied to the debit memo item.
tax_code:
type: string
description: The designated tax code.
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the debit memo
item.
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this debit memo
item.
invoice_item_id:
type: string
description: >-
The identifier of the invoice item associated with this debit memo
item.
document_item_date:
type: string
format: date-time
description: The date when the debit memo item takes effect.
example: '2022-01-01T07:08:12-07:00'
taxation_items:
type: object
title: TaxationItemListResponse
description: Information of the taxation items.
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/taxationItem'
debit_memo:
allOf:
- $ref: '#/components/schemas/debitMemo'
description: The related debit memo. EXPANDABLE
debit_memo_id:
type: string
description: The related debit memo id.
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
readOnly: true
description: List of customer subscriptions.
subscription_item:
allOf:
- $ref: '#/components/schemas/subscriptionItem'
description: >-
The expandable subscription item associated with this billing
document item.
payDebitMemoRequest:
type: object
title: PayDebitMemoRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: The amount of the payment.
account_id:
type: string
description: Identifier of the account that owns the debit memo.
account_number:
type: string
description: Human-readable identifier of the account that owns the debit memo.
authorization_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled and are creating a debit memo from a charge.
bank_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
payment_date:
type: string
format: date
description: The date and time when the payment takes effect.
payment_method_id:
type: string
description: Identifier of the payment method used to create this payment.
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
this payment.
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
payment gateway when a payment is created. If not specified, the
payment number will be passed in instead.
reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this payment is not handled by Zuora.
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- currency
debitMemoItemListResponse:
type: object
title: DebitMemoItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/debitMemoItem'
creditMemo:
type: object
title: CreditMemo
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: >-
Identifier of the account that owns the credit memo. **Either
this field or `account_number` is required when creating credit
memos from a price(charge in the v1 API).**
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
document_date:
type: string
format: date
description: The date when the credit memo takes effect.
example: '2023-01-01'
reason_code:
type: string
description: Reason for issuing this credit memo
invoice_id:
type: string
description: >-
The identifier of the invoice billing document from which this
credit memo is created. **Required when creating credit memos
from an invoice.**
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo from the rule of
automatically applying it to invoices.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled and are creating a credit memo from a charge.
credit_memo_number:
type: string
readOnly: true
description: >-
A human-readable identifier for the billing document; may be
user-supplied.
amount_refunded:
type: number
description: The amount this billing document refunded.
state_transitions:
allOf:
- type: object
properties:
posted_time:
type: string
readOnly: true
canceled_time:
type: string
readOnly: true
posted_by_id:
type: string
readOnly: true
description: Identifier of the Zuora user who posted the billing document.
state:
type: string
enum:
- draft
- posted
- canceled
- failed
description: The status of the billing document.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the billing document. EXPANDABLE
items:
allOf:
- $ref: '#/components/schemas/creditMemoItemListResponse'
readOnly: true
description: List of billing document items. EXPANDABLE
total:
type: number
readOnly: true
description: The total amount.
subtotal:
type: number
readOnly: true
description: The total amount exclusive of tax.
tax:
type: number
readOnly: true
description: The total tax amount.
balance:
type: number
readOnly: true
deprecated: true
description: >-
The total balance remaining. This field is deprecated. Use
`remaining_balance` field.
remaining_balance:
type: number
readOnly: true
description: The total balance remaining.
applied_to:
type: array
items:
$ref: '#/components/schemas/creditMemoAppliedToResponse'
readOnly: true
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
creditMemoListResponse:
type: object
title: CreditMemoListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/creditMemo'
creditMemoCreateRequest:
type: object
title: CreditMemoCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
account_id:
type: string
description: >-
Identifier of the account that owns the credit memo. **Either
this field or `account_number` is required when creating credit
memos from a price(charge in the v1 API).**
account_number:
type: string
description: >-
Human-readable identifier of the account that owns the credit
memo. **Either this field or `account_id` is required when
creating credit memos from a price(charge in the v1 API).**
example: RC-00020831
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
document_date:
type: string
format: date
description: The date when the credit memo takes effect.
example: '2023-01-01'
reason_code:
type: string
description: Reason for issuing this credit memo
invoice_id:
type: string
description: >-
The identifier of the invoice billing document from which this
credit memo is created. **Required when creating credit memos
from an invoice.**
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
custom_fields:
$ref: '#/components/schemas/customFields'
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo from the rule of
automatically applying it to invoices.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled and are creating a credit memo from a charge.
items:
type: array
items:
$ref: '#/components/schemas/creditMemoItemCreateRequest'
description: Information of all credit memo items.
apply:
type: boolean
description: Whether to automatically apply the billing document upon posting.
post:
type: boolean
description: >-
Whether to automatically post a billing document after it is
created.
creditMemoItem:
type: object
title: CreditMemoItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
amount:
type: number
description: The total amount of this credit memo item.
subtotal:
type: number
description: The total amount of this credit memo item exclusive of tax.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: >-
The accounting code for the deferred revenue, such as Monthly
Recurring Liability.
on_account_account:
type: string
description: >-
The accounting code that maps to an on account in your accounting
system.
recognized_revenue_account:
type: string
description: >-
The accounting code for the recognized revenue, such as Monthly
Recurring Charges or Overage Charges.
credit_memo:
allOf:
- $ref: '#/components/schemas/creditMemo'
description: The related credit memo. EXPANDABLE
credit_memo_id:
type: string
description: The related credit memo id.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
description: >-
The end date of the service period associated with this credit memo
item. If the associated charge is a one-time fee, then this date is
the date of that charge.
service_start:
type: string
description: >-
The start date of the service period associated with this credit
memo item. If the associated charge is a one-time fee, then this
date is the date of that charge.
accounts_receivable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
discount_item:
type: boolean
description: If true, indicates that the item is a discount item.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item that this credit memo item is applied
to.
accounting_code:
type: string
description: An active account in your Zuora Chart of Accounts.
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
tax_inclusive:
type: boolean
description: >-
This specifies if the credit memo item amount is inclusive or
exclusive of tax.
remaining_balance:
type: number
description: The remaining balance of this credit memo item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
unit_amount:
type: number
description: Unit amount of the credit memo item.
name:
type: string
description: >-
Name of the credit memo item displayed to customers on the billing
document.
price_id:
type: string
description: >-
The identifier of the price this credit memo item is associated
with.
purchase_order_number:
type: string
description: The purchase order number associated with this credit memo item.
tax:
type: number
description: The amount of tax applied to the credit memo item.
tax_code:
type: string
description: The designated tax code.
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the credit memo
item.
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this credit
memo item.
invoice_item_id:
type: string
description: >-
The identifier of the invoice item associated with this credit memo
item.
document_item_date:
type: string
format: date-time
description: The date when the credit memo item takes effect.
example: '2022-01-01T07:08:12-07:00'
taxation_items:
type: object
title: TaxationItemListResponse
description: Information of the taxation items.
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/taxationItem'
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
readOnly: true
description: List of customer subscriptions.
subscription_item:
allOf:
- $ref: '#/components/schemas/subscriptionItem'
description: >-
The expandable subscription item associated with this billing
document item.
creditMemoItemListResponse:
type: object
title: CreditMemoItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/creditMemoItem'
creditMemoItemCreateRequest:
type: object
title: CreditMemoItemCreateRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: >-
Amount of the credit memo item. This should always be equal to
unit_amount * quantity. Required when creating credit memos
from an invoice.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
recognized_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
format: date
description: >-
The end date of the service period associated with this credit memo
item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
service_start:
type: string
format: date
description: >-
The start date of the service period associated with this credit
memo item. If the price for the associated subscription item is a
one-time fee, then this date is the date of that subscription item.
example: '2022-01-01'
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
tax_inclusive:
type: boolean
description: >-
Indicates whether the credit memo item amount is inclusive or
exclusive of tax.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
taxation_items:
type: array
items:
$ref: '#/components/schemas/taxationItemCreateRequest'
description: List of taxation items.
unit_amount:
type: number
description: Unit amount of the credit memo item.
price_id:
type: string
description: >-
The identifier of the price this credit memo item is associated
with. Required when creating credit memos from a price(charge in
the v1 API).
purchase_order_number:
type: string
description: >-
The purchase order number associated with this billing document
item.
tax_code:
type: string
description: The designated tax code.
name:
type: string
description: >-
Name of the billing document item displayed to customers on the
billing document. **Required when creating credit memos from an
invoice**
invoice_item_id:
type: string
description: >-
The identifier of the invoice item associated with this credit memo
item. **Required when creating credit memos from an invoice.**
accounting_code:
type: string
description: An active account in your Zuora Chart of Accounts.
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- service_start
refundCreditMemoItemRequest:
type: object
title: RefundCreditMemoItemRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Identifier of the credit memo item.
amount:
type: number
description: Refund amount.
tax_item_id:
type: string
description: Identifier of the credit memo taxation item.
required:
- amount
refundCreditMemoTaxationItemRequest:
type: object
title: RefundCreditMemoTaxationItemRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Identifier of the credit memo taxation item.
amount:
type: number
description: Refund amount.
required:
- amount
refundCreditMemoRequest:
type: object
title: RefundCreditMemoRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Identifier of the credit memo taxation item
amount:
type: number
description: Refund amount.
credit_memo_items:
type: array
items:
$ref: '#/components/schemas/refundCreditMemoItemRequest'
description: The credit memo items where the refund is applied.
taxation_items:
type: array
items:
$ref: '#/components/schemas/refundCreditMemoTaxationItemRequest'
description: The taxation items of the credit memo where the refund is applied.
required:
- amount
creditMemoAppliedToResponse:
type: object
title: CreditMemoAppliedToResponse
description: ''
nullable: false
additionalProperties: false
properties:
billing_document_id:
type: string
description: Identifier of an invoice or a debit memo.
id:
type: string
description: Identifier of the credit memo application
amount:
type: number
description: >-
The amount of the payment that is applied to the specific billing
document item or taxation item.
billing_document:
allOf:
- $ref: '#/components/schemas/billingDocument'
description: The related billing document.
billing_document_type:
type: string
enum:
- debit_memo
- invoice
description: >-
The type of billing document. Can be one of the debit memo or
invoice.
creditMemoItemApplicationRequest:
type: object
title: CreditMemoItemApplicationRequest
description: ''
additionalProperties: false
properties:
credit_memo_item_id:
type: string
description: The identifier of the credit memo item to apply.
amount:
type: number
description: >-
The credit memo amount applied to this billing document item or
taxation item.
credit_memo_taxation_item_id:
type: string
description: The identifier of the credit memo taxation item to apply.
taxation_item_id:
type: string
description: The identifier of a taxation item.
id:
type: string
description: The identifier of an invoice item or debit memo item.
required:
- amount
applyUnapplyCreditMemo:
type: object
title: ApplyUnapplyCreditMemo
description: ''
additionalProperties: false
properties:
effective_date:
type: string
format: date
description: The date when the credit memo is applied
example: '2023-01-01'
billing_documents:
type: array
items:
$ref: '#/components/schemas/creditMemoApplicationRequest'
description: Array of billing documents to apply this credit memo to.
required:
- billing_documents
creditMemoApplicationRequest:
type: object
title: CreditMemoApplicationRequest
description: ''
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the invoice or debit memo to which the credit memo is
applied.
type:
type: string
enum:
- debit_memo
- invoice
description: The type of billing document, one of invoice or debit_memo.
amount:
type: number
description: The credit memo amount applied to this billing document.
items:
type: array
items:
$ref: '#/components/schemas/creditMemoItemApplicationRequest'
description: >-
The billing document items (invoice items or debit memo items or
taxation items) to which the credit memo is applied.
required:
- type
- id
- amount
creditMemoPatchRequest:
type: object
title: CreditMemoPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
apply:
type: boolean
description: Whether to automatically apply the billing document upon posting.
document_date:
type: string
format: date
description: The date when the credit memo is applied
example: '2023-01-01'
reason_code:
type: string
description: Reason for issuing this credit memo
transfer_to_accounting:
type: boolean
description: Whether to transfer to an external accounting system.
exclude_from_auto_apply_rules:
type: boolean
description: >-
Indicates whether to exclude this credit memo from the rule of
automatically applying it to invoices.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
custom_fields:
$ref: '#/components/schemas/customFields'
refund:
type: object
title: Refund
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
amount:
type: number
description: Refund amount.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
refund_date:
type: string
format: date
description: The date when the refund takes effect.
refund_method_type:
type: string
enum:
- cash
- check
- wire_transfer
- pay_pal
- credit_card
- cc_ref
- ach_debit
- debit_card
- other
payment_id:
type: string
readOnly: true
description: Identifier for the payment, either `payment_number` or `payment_id.
reason_code:
type: string
description: User-provided reason for the refund.
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this refund is not handled by Zuora.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile refunds between your payment gateway and
Zuora Payments.
second_reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
bank_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
unapplied_payment_account:
type: string
description: An active account in your Zuora Chart of Accounts.
payment_method_id:
type: string
readOnly: true
description: Identifier of the payment method used to create this refund.
credit_memo:
allOf:
- $ref: '#/components/schemas/refundCreditMemoRequest'
description: The related credit memo.
account_id:
type: string
description: Identifier of the customer this refund is for, if one exists.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the refund
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
the payments that are made with this payment method. If you do not
set this field, Zuora will use one of the following payment gateways
instead: The default payment gateway of the customer account that
owns the payment method, if the payment method is associated with a
customer account or the default payment gateway of your Zuora
tenant.
comment:
type: string
description: Comments about the refund.
gateway_response:
type: string
readOnly: true
description: Message returned by the payment gateway for this refund.
gateway_response_code:
type: string
readOnly: true
description: Code returned by the payment gateway for this refund.
gateway_state:
type: string
enum:
- marked_for_submission
- submitted
- settled
- not_submitted
- failed
readOnly: true
description: The payment gateway state of the refund.
payment_method:
type: object
title: PaymentMethod
description: Payment method information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601
UTC format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful
for storing additional information about the object in a
structured format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
enum:
- paypal_express
- paypal_express_native
- paypal_adaptive
- card
- cc_ref
- ach_debit
- sepa_debit
- betalings_debit
- autogiro_debit
- bacs_debit
- au_becs_debit
- nz_becs_debit
- pad_debit
- apple_pay
- wire_transfer
- check
- cash
- other
- paypal
- adyen_google_pay
- adyen_apple_pay
description: >-
The type of the payment method. An additional hash is included
on the payment method with a name matching this value. It
contains additional information specific to the payment method
type.
custom_type:
type: string
description: >-
The custom type of the payment method from Universal Payment
Connector.
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account:
allOf:
- $ref: '#/components/schemas/account'
readOnly: true
description: The customer account associated with this payment method.
billing_details:
type: object
title: BillingDetails
description: >-
Billing information associated with the payment method that may
be used or required by specific payment method types.
additionalProperties: false
properties:
name:
type: string
description: Customer full name or business name.
example: Amy Lawrence
address:
type: object
title: AddressFieldDefinitions
description: Address information used in billing details.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: >-
Address line 2 (e.g., apartment, suite, unit, or
building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
country:
type: string
description: The country of the contact's address.
example: United States
state:
type: string
description: The state, county, province, or region.
example: GA
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
phone:
type: string
description: Customer phone (including extension).
example: (888)976-9056
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts
using this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
ip_address:
type: string
nullable: true
description: >-
The IP address from which the Mandate was accepted by the
customer.
example: 192.10.1.123
bank_identification_number:
type: string
card:
type: object
title: GetCardList
description: Credit card information.
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's expiration
year.
example: 2024
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
paypal_express_native:
type: object
title: PaypalExpressNative
description: >-
If it is a `paypal_express_native` payment method, this hash
contains details about the PayPal Express Native payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: >-
Email address associated with the payment method. This is
required with a paypal_express_checkout or a paypal_adaptive
payment method.
required:
- baid
paypal_express:
type: object
title: PaypalExpress
description: >-
If it is a `paypal_express` payment method, this hash contains
details about the PayPal Express payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: Email address associated with the payment method
required:
- baid
- email
paypal_adaptive:
type: object
title: PaypalAdaptive
description: >-
If it is a `paypal_adaptive` payment method, this hash contains
details about the PayPal Adaptive payment method.
additionalProperties: false
properties:
preapproval_key:
type: string
description: PayPal preapproval key.
example: 2G4EPFSD
email:
type: string
description: Email address associated with the payment method.
example: alawrence@zuora.com
required:
- preapproval_key
- email
sepa_debit:
type: object
title: SepaDebit
description: >-
If the `type` of the payment method is `sepa_debit`, this hash
contains details about the SEPA bank account.
additionalProperties: false
properties:
IBAN:
type: string
description: >-
International Bank Account Number used to create the SEPA
Debit payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
business_identification_code:
type: string
description: The BIC code used with the Sepa Debit payment method.
required:
- IBAN
cc_ref:
type: object
title: CcRef
description: >-
If the `type` of the payment method is `cc_ref`, this hash
contains details about the Credit Card Reference Transactions
payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
second_token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data. This field is conditionally required only when
`token` is being used to represent a gateway customer
profile.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
card:
type: object
title: CcRefCard
description: ''
nullable: false
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: >-
One or two digit expiration month (1-12) of the credit
card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's
expiration year.
example: 2024
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
required:
- token
apple_pay:
type: object
title: ApplePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you
must meet the requirements for PCI compliance. We strongly
recommend using Zuora.js instead of interacting with this
API directly.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
payment_id:
type: string
description: >-
The ID of newly processed payment. Only available in the
response of the Create Payment Method API request.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
google_pay:
type: object
title: GooglePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you
must meet the requirements for PCI compliance. We strongly
recommend using Zuora.js instead of interacting with this
API directly.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
ach_debit:
type: object
title: AchDebit
description: >-
If the `type` of the payment method is `ach_debit`, this hash
contains details about the ACH bank account.
additionalProperties: false
properties:
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
bank_aba_code:
type: string
description: The nine-digit routing number or ABA number used by banks.
bank_account_name:
type: string
description: >-
The name of the account holder, which can be either a person
or a company.
bank_account_type:
type: string
enum:
- business_saving
- business_checking
- checking
- saving
description: The type of bank account associated with the payment method.
bank_name:
type: string
description: Name of the bank associated with this bank account.
bank_account_number:
type: string
description: The bank account number of the account holder.
required:
- bank_aba_code
- bank_account_type
- bank_account_name
- bank_account_number
- bank_name
betalings_debit:
type: object
title: BetalingsDebit
description: >-
If the `type` of the payment method is `betalings_debit`, this
hash contains details about the Betalingsservice bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: >-
The identity number used for Betalingsservice (Direct Debit
DK).
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- identity_number
- bank_code
autogiro_debit:
type: object
title: AutogiroDebit
description: >-
If the `type` of the payment method is `autogiro_debit`, this
hash contains details about the Autogiro bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Autogiro (Direct Debit SE).
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- identity_number
- branch_code
bacs_debit:
type: object
title: BacsDebit
description: >-
If the `type` of the payment method is `bacs_debit`,, this hash
contains details about the BACS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- bank_code
au_becs_debit:
type: object
title: AuBecsDebit
description: >-
If the `type` of the payment method is `au_becs_debit`, this
hash contains details about the BECS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
nz_becs_debit:
type: object
title: NzBecsDebit
description: >-
If the `type` of the payment method is `nz_becs_debit`, this
hash contains details about the BECS-NZ bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
pad_debit:
type: object
title: PadDebit
description: >-
If the `type` of the payment method is `pad_debit`, this hash
contains details about the PAD bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
state:
type: string
enum:
- active
- closed
- scrubbed
description: The state of the payment method.
auto_generated:
type: boolean
use_default_retry_rule:
type: boolean
existing_mandate:
type: boolean
last_failed_sale_transaction_time:
type: string
format: date-time
last_transaction_time:
type: string
format: date-time
last_transaction_status:
type: string
number_of_consecutive_failures:
type: integer
total_number_of_processed_payments:
type: integer
total_number_of_error_payments:
type: integer
refund_number:
type: string
description: Human-readable identifier for this object; may be user-supplied.
state_transitions:
type: object
title: RefundStateTransitions
description: The timestamps at which the object's state was updated.
additionalProperties: false
properties:
canceled_time:
type: string
format: date-time
description: >-
The date and time (ISO 8601 UTC format) when the refund was
canceled.
refunded_time:
type: string
format: date-time
state:
type: string
enum:
- draft
- posted
- processing
- processed
- error
- canceled
readOnly: true
description: The state of the refund.
gateway_reconciliation_reason:
type: string
readOnly: true
description: Gateway reconciliation reason.
gateway_reconciliation_status:
type: string
readOnly: true
description: Gateway reconciliation state.
payout_id:
type: string
readOnly: true
description: Identifier of the payout from the payment gateway.
applied_to:
type: array
items:
$ref: '#/components/schemas/refundsAppliedToResponse'
readOnly: true
refundCreateRequest:
type: object
title: RefundCreateRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: Refund amount.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
refund_date:
type: string
format: date
description: The date when the refund takes effect.
refund_method_type:
type: string
enum:
- cash
- check
- wire_transfer
- pay_pal
- credit_card
- cc_ref
- ach_debit
- debit_card
- other
payment_id:
type: string
readOnly: true
description: Identifier for the payment, either `payment_number` or `payment_id.
reason_code:
type: string
description: User-provided reason for the refund.
statement_descriptor:
type: string
maxLength: 35
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
maxLength: 20
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this refund is not handled by Zuora.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile refunds between your payment gateway and
Zuora Payments.
second_reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
bank_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
unapplied_payment_account:
type: string
description: An active account in your Zuora Chart of Accounts.
custom_fields:
$ref: '#/components/schemas/customFields'
payment_method_id:
type: string
readOnly: true
description: Identifier of the payment method used to create this refund.
credit_memo:
allOf:
- $ref: '#/components/schemas/refundCreditMemoRequest'
description: The related credit memo.
billing_documents:
type: array
items:
$ref: '#/components/schemas/billingDocumentPaymentApplicationRequest'
description: >-
Indicates to which billing documents (invoices or debit memos) is
the refund applied.
required:
- amount
refundPatchRequest:
type: object
title: RefundPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
reason_code:
type: string
description: User-provided reason for the refund.
bank_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
unapplied_payment_account:
type: string
description: An active account in your Zuora Chart of Accounts.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile payments between your payment gateway and
Zuora Payments.
custom_fields:
$ref: '#/components/schemas/customFields'
refundListResponse:
type: object
title: RefundListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/refund'
refundsAppliedToResponse:
type: object
title: RefundsAppliedToResponse
description: ''
nullable: false
additionalProperties: false
properties:
billing_document_id:
type: string
description: Identifier of an invoice or a debit memo.
id:
type: string
description: Identifier of the refund application.
billing_document:
allOf:
- $ref: '#/components/schemas/billingDocument'
description: The related billing document.
amount:
type: number
description: >-
The amount of the payment that is applied to the specific billing
document item or taxation item.
billing_document_type:
type: string
enum:
- credit_memo
- invoice
description: >-
The type of billing document. Can be one of the credit memo or
invoice.
payment:
allOf:
- $ref: '#/components/schemas/payment'
items:
type: array
items:
$ref: '#/components/schemas/refundAppliedToItemResponse'
description: The related credit memo item.
refundAppliedToItemResponse:
type: object
title: RefundAppliedToItemResponse
description: ''
nullable: false
additionalProperties: false
properties:
credit_memo_item_id:
type: string
description: Identifier of an invoice or a debit memo item.
id:
type: string
description: Identifier of the payment application item.
amount:
type: number
description: >-
The amount of the payment that is applied to the specific billing
document item.
taxation_item_id:
type: string
description: Identifier of a taxation item.
paymentPatchRequest:
type: object
title: PaymentPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile payments between your payment gateway and
Zuora Payments.
paymentCreateRequest:
type: object
title: PaymentCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile payments between your payment gateway and
Zuora Payments.
account_id:
type: string
description: Identifier of the customer account associated with this payment.
account_number:
type: string
description: >-
Human-readable identifier of the account associated with this
payment. It can be user-supplied.
amount:
type: number
description: The total amount of the payment.
authorization_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
payment_date:
type: string
format: date
description: The date and time when the payment takes effect.
payment_method_id:
type: string
description: Identifier of the payment method used to create this payment.
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
this payment.
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
payment gateway when a payment is created. If not specified, the
payment number will be passed in instead.
second_reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this payment is not handled by Zuora.
currency:
type: string
description: 3-letter ISO 4217 currency code.
billing_documents:
type: array
items:
$ref: '#/components/schemas/billingDocumentPaymentApplicationRequest'
description: >-
Indicates to which billing documents (invoices or debit memos) are
the payment applied.
required:
- payment_date
- payment_method_id
- currency
- amount
payment:
type: object
title: Payment
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
reference_id:
type: string
description: >-
Transaction identifier returned by the payment gateway. You may use
this field to reconcile payments between your payment gateway and
Zuora Payments.
account_id:
type: string
description: Identifier of the customer account associated with this payment.
account_number:
type: string
description: >-
Human-readable identifier of the account associated with this
payment. It can be user-supplied.
amount:
type: number
description: The total amount of the payment.
authorization_id:
type: string
description: >-
Identifier of the authorization transaction from the payment
gateway.
payment_date:
type: string
format: date
description: The date and time when the payment takes effect.
payment_method_id:
type: string
description: Identifier of the payment method used to create this payment.
gateway_id:
type: string
description: >-
Identifier of the payment gateway that Zuora will use to authorize
this payment.
gateway_order_id:
type: string
description: >-
A merchant-specified natural key value that can be passed to the
payment gateway when a payment is created. If not specified, the
payment number will be passed in instead.
second_reference_id:
type: string
description: >-
A second transaction identifier returned by the payment gateway if
there is an additional transaction for the refunds. You may use this
field to reconcile payments between your payment gateway and Zuora
Payments.
gateway_options:
type: object
additionalProperties:
type: string
example:
key: value
statement_descriptor:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
statement_descriptor_phone:
type: string
description: A payment gateway-specific field used by Orbital, Vantiv and Verifi.
external:
type: boolean
description: If true, indicates that this payment is not handled by Zuora.
currency:
type: string
description: 3-letter ISO 4217 currency code.
account:
allOf:
- $ref: '#/components/schemas/account'
description: The customer account associated with this payment.
amount_applied:
type: number
description: The total amount applied.
remaining_balance:
type: number
description: The total remaining balance.
amount_refunded:
type: number
description: The total amount refunded.
state:
type: string
enum:
- draft
- posted
- processing
- processed
- error
- canceled
readOnly: true
description: The state of the payment.
payout_id:
type: string
description: Identifier of the payout associated with this payment.
payment_number:
type: string
description: Human-readable identifier for this object; may be user-supplied.
gateway_response_code:
type: string
description: Code returned by the payment gateway for this payment.
payment_method:
type: object
title: PaymentMethod
description: Payment method information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601
UTC format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful
for storing additional information about the object in a
structured format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
type:
type: string
enum:
- paypal_express
- paypal_express_native
- paypal_adaptive
- card
- cc_ref
- ach_debit
- sepa_debit
- betalings_debit
- autogiro_debit
- bacs_debit
- au_becs_debit
- nz_becs_debit
- pad_debit
- apple_pay
- wire_transfer
- check
- cash
- other
- paypal
- adyen_google_pay
- adyen_apple_pay
description: >-
The type of the payment method. An additional hash is included
on the payment method with a name matching this value. It
contains additional information specific to the payment method
type.
custom_type:
type: string
description: >-
The custom type of the payment method from Universal Payment
Connector.
account_id:
type: string
description: A customer account identifier.
example: 2c92c0f86a8dd422016a9e7a70116b0d
account:
allOf:
- $ref: '#/components/schemas/account'
readOnly: true
description: The customer account associated with this payment method.
billing_details:
type: object
title: BillingDetails
description: >-
Billing information associated with the payment method that may
be used or required by specific payment method types.
additionalProperties: false
properties:
name:
type: string
description: Customer full name or business name.
example: Amy Lawrence
address:
type: object
title: AddressFieldDefinitions
description: Address information used in billing details.
additionalProperties: false
properties:
line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
example: 3333 Piedmont Rd NE
line2:
type: string
description: >-
Address line 2 (e.g., apartment, suite, unit, or
building).
example: Suite 1150
city:
type: string
description: City, district, suburb, town, or village.
example: Atlanta
country:
type: string
description: The country of the contact's address.
example: United States
state:
type: string
description: The state, county, province, or region.
example: GA
postal_code:
type: string
description: ZIP or postal code.
example: '30305'
email:
type: string
description: Customer email address.
example: alawrence@gmail.com
phone:
type: string
description: Customer phone (including extension).
example: (888)976-9056
maximum_payment_attempts:
type: number
description: >-
Maximum number of consecutive failed retry payment attempts
using this payment method before retries are stopped.
example: 6
payment_retry_interval:
type: integer
description: The retry interval in hours.
example: 3
device_session_id:
type: string
ip_address:
type: string
nullable: true
description: >-
The IP address from which the Mandate was accepted by the
customer.
example: 192.10.1.123
bank_identification_number:
type: string
card:
type: object
title: GetCardList
description: Credit card information.
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: One or two digit expiration month (1-12) of the credit card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's expiration
year.
example: 2024
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
paypal_express_native:
type: object
title: PaypalExpressNative
description: >-
If it is a `paypal_express_native` payment method, this hash
contains details about the PayPal Express Native payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: >-
Email address associated with the payment method. This is
required with a paypal_express_checkout or a paypal_adaptive
payment method.
required:
- baid
paypal_express:
type: object
title: PaypalExpress
description: >-
If it is a `paypal_express` payment method, this hash contains
details about the PayPal Express payment method.
additionalProperties: false
properties:
baid:
type: string
description: >-
Identifier of a PayPal billing agreement. For example,
I-1TJ3GAGG82Y9.
email:
type: string
description: Email address associated with the payment method
required:
- baid
- email
paypal_adaptive:
type: object
title: PaypalAdaptive
description: >-
If it is a `paypal_adaptive` payment method, this hash contains
details about the PayPal Adaptive payment method.
additionalProperties: false
properties:
preapproval_key:
type: string
description: PayPal preapproval key.
example: 2G4EPFSD
email:
type: string
description: Email address associated with the payment method.
example: alawrence@zuora.com
required:
- preapproval_key
- email
sepa_debit:
type: object
title: SepaDebit
description: >-
If the `type` of the payment method is `sepa_debit`, this hash
contains details about the SEPA bank account.
additionalProperties: false
properties:
IBAN:
type: string
description: >-
International Bank Account Number used to create the SEPA
Debit payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
business_identification_code:
type: string
description: The BIC code used with the Sepa Debit payment method.
required:
- IBAN
cc_ref:
type: object
title: CcRef
description: >-
If the `type` of the payment method is `cc_ref`, this hash
contains details about the Credit Card Reference Transactions
payment method. See [Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
second_token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data. This field is conditionally required only when
`token` is being used to represent a gateway customer
profile.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
card:
type: object
title: CcRefCard
description: ''
nullable: false
additionalProperties: false
properties:
brand:
type: string
enum:
- visa
- mastercard
- american_express
- discover
- jcb
- diners
description: Card brand.
expiry_month:
type: number
description: >-
One or two digit expiration month (1-12) of the credit
card.
example: 10
expiry_year:
type: number
description: >-
Two- or four-digit number representing the card's
expiration year.
example: 2024
last_4:
type: string
readOnly: true
description: The last four digits of the card number.
example: '2042'
required:
- token
apple_pay:
type: object
title: ApplePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you
must meet the requirements for PCI compliance. We strongly
recommend using Zuora.js instead of interacting with this
API directly.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
payment_id:
type: string
description: >-
The ID of newly processed payment. Only available in the
response of the Create Payment Method API request.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
google_pay:
type: object
title: GooglePay
description: >-
If the `type` of the payment method is `apple_pay`, this hash
contains details about the Apple Pay payment method. See
[Supported payment
methods](https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods)
for payment gateways that support this type of payment method.
additionalProperties: false
properties:
card:
allOf:
- $ref: '#/components/schemas/getCardList'
description: >-
Credit card information. When providing a card number, you
must meet the requirements for PCI compliance. We strongly
recommend using Zuora.js instead of interacting with this
API directly.
token:
type: string
description: >-
A gateway unique identifier that replaces sensitive payment
method data or represents a gateway's unique customer
profile. When `token` is used to represent a customer
profile, `second_token` is conditionally required for
representing the underlying tokenized payment method.
ach_debit:
type: object
title: AchDebit
description: >-
If the `type` of the payment method is `ach_debit`, this hash
contains details about the ACH bank account.
additionalProperties: false
properties:
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
bank_aba_code:
type: string
description: The nine-digit routing number or ABA number used by banks.
bank_account_name:
type: string
description: >-
The name of the account holder, which can be either a person
or a company.
bank_account_type:
type: string
enum:
- business_saving
- business_checking
- checking
- saving
description: The type of bank account associated with the payment method.
bank_name:
type: string
description: Name of the bank associated with this bank account.
bank_account_number:
type: string
description: The bank account number of the account holder.
required:
- bank_aba_code
- bank_account_type
- bank_account_name
- bank_account_number
- bank_name
betalings_debit:
type: object
title: BetalingsDebit
description: >-
If the `type` of the payment method is `betalings_debit`, this
hash contains details about the Betalingsservice bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: >-
The identity number used for Betalingsservice (Direct Debit
DK).
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- identity_number
- bank_code
autogiro_debit:
type: object
title: AutogiroDebit
description: >-
If the `type` of the payment method is `autogiro_debit`, this
hash contains details about the Autogiro bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
identity_number:
type: string
description: The identity number used for Autogiro (Direct Debit SE).
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- identity_number
- branch_code
bacs_debit:
type: object
title: BacsDebit
description: >-
If the `type` of the payment method is `bacs_debit`,, this hash
contains details about the BACS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- bank_code
au_becs_debit:
type: object
title: AuBecsDebit
description: >-
If the `type` of the payment method is `au_becs_debit`, this
hash contains details about the BECS bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
nz_becs_debit:
type: object
title: NzBecsDebit
description: >-
If the `type` of the payment method is `nz_becs_debit`, this
hash contains details about the BECS-NZ bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
pad_debit:
type: object
title: PadDebit
description: >-
If the `type` of the payment method is `pad_debit`, this hash
contains details about the PAD bank account.
additionalProperties: false
properties:
account_number:
type: string
description: The bank account number of the account holder.
branch_code:
type: string
description: >-
Identifier of the bank branch associated with this bank
account.
bank_code:
type: string
description: Identifier of the bank associated with this bank account.
mandate:
type: object
title: Mandate
description: >-
The mandate information for the Credit Card, Credit Card
Reference Transaction, ACH, or Bank Transfer payment method.
additionalProperties: false
properties:
id:
type: string
description: >-
Identifier of the single- or multi-use mandate generated
by the payment gateway.
reason:
type: string
description: Reason for the mandate.
state:
type: string
enum:
- active
- canceled
- expired
- agreed
readOnly: true
description: >-
The status of the mandate, which indicates whether it
can be used to initiate a payment.
required:
- account_number
- branch_code
- bank_code
state:
type: string
enum:
- active
- closed
- scrubbed
description: The state of the payment method.
auto_generated:
type: boolean
use_default_retry_rule:
type: boolean
existing_mandate:
type: boolean
last_failed_sale_transaction_time:
type: string
format: date-time
last_transaction_time:
type: string
format: date-time
last_transaction_status:
type: string
number_of_consecutive_failures:
type: integer
total_number_of_processed_payments:
type: integer
total_number_of_error_payments:
type: integer
gateway_response:
type: string
description: Message returned by the payment gateway for this payment.
gateway_reconciliation_status:
type: string
description: Gateway reconciliation state.
gateway_reconciliation_reason:
type: string
description: Gateway reconciliation reason.
gateway_state:
type: string
enum:
- marked_for_submission
- submitted
- settled
- not_submitted
- failed
readOnly: true
description: The payment gateway state of the payment.
applied_to:
type: array
items:
$ref: '#/components/schemas/paymentsAppliedToResponse'
readOnly: true
payment_schedule_items:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItem'
state_transitions:
type: object
title: PaymentStateTransitions
description: The timestamps at which the object's state was updated.
additionalProperties: false
properties:
canceled_time:
type: string
format: date-time
description: >-
The date and time (ISO 8601 UTC format) when the payment was
canceled.
gateway_state_transitions:
type: object
title: GatewayStateTransitions
description: ''
nullable: false
additionalProperties: false
properties:
marked_for_submission_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time (ISO 8601 UTC format) when the payment was
marked for submission.
settled_time:
type: string
format: date-time
description: >-
The date and time (ISO 8601 UTC format) when the payment was
settled.
submitted_time:
type: string
format: date-time
description: >-
The date and time (ISO 8601 UTC format) when the payment was
submitted.
paymentsAppliedToResponse:
type: object
title: PaymentsAppliedToResponse
description: ''
nullable: false
additionalProperties: false
properties:
billing_document_id:
type: string
description: Identifier of an invoice or a debit memo.
id:
type: string
description: Identifier of the payment application.
amount:
type: number
description: >-
The amount of the payment that is applied to the specific billing
document item or taxation item.
billing_document:
allOf:
- $ref: '#/components/schemas/billingDocument'
description: The related billing document.
billing_document_type:
type: string
enum:
- debit_memo
- invoice
description: >-
The type of billing document. Can be one of the debit memo or
invoice.
state:
type: string
enum:
- draft
- posted
- processing
- processed
- error
- canceled
readOnly: true
items:
type: array
items:
$ref: '#/components/schemas/paymentAppliedToBillingItemResponse'
description: The related billing document item.
paymentApplyUnapplyRequest:
type: object
title: PaymentApplyUnapplyRequest
description: ''
additionalProperties: false
properties:
effective_date:
type: string
format: date
description: The date and time when the payment takes effect.
billing_documents:
type: array
items:
$ref: '#/components/schemas/billingDocumentPaymentApplicationRequest'
description: >-
Indicates to which billing documents (invoices or debit memos) are
the payment applied.
required:
- billing_documents
paymentListResponse:
type: object
title: PaymentListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/payment'
paymentAppliedToBillingItemResponse:
type: object
title: PaymentAppliedToBillingItemResponse
description: ''
nullable: false
additionalProperties: false
properties:
billing_document_item_id:
type: string
description: Identifier of an invoice or a debit memo item.
id:
type: string
description: Identifier of the payment application item.
billing_document_item:
allOf:
- $ref: '#/components/schemas/billingDocumentItem'
description: The related billing document item.
amount:
type: number
description: >-
The amount of the payment that is applied to the specific billing
document item.
billing_document_id:
type: string
description: Identifier of an invoice or a debit memo.
taxation_item_id:
type: string
description: Identifier of a taxation item.
writeOffSuscriptionRequest:
type: object
title: WriteOffSuscriptionRequest
description: >-
The financial information of the credit memo items generated to write
off the invoice balance.
additionalProperties: false
properties:
on_account_accounting_code:
type: string
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_accounting_code:
type: string
description: An active accounting code in your Zuora chart of accounts.
recognized_revenue_accounting_code:
type: string
description: An active accounting code in your Zuora chart of accounts.
revenue_recognition_rule_name:
type: string
description: Name of the revenue recognition rule that you want to apply.
processingOptions:
type: object
title: ProcessingOptions
description: Processing options for the invoice or payment.
additionalProperties: false
properties:
document_date:
type: string
format: date
description: The date printed on billing documents.
target_date:
type: string
format: date
description: >-
The target date for the order to be picked up by bill run for
billing.
collection_method:
type: string
enum:
- collect_payment
- create_invoice
- process_refund
- run_billing
description: >-
Specifies whether to just create an invoice, or to create an invoice
and collect payment.
payment_method_id:
type: string
description: Payment method Id used to pay billing documents.
draft_invoice:
type: boolean
payment_gateway_id:
type: string
refund_reason_code:
type: string
term:
type: object
title: Term
description: Term information of the subscription.
additionalProperties: false
properties:
interval_count:
type: integer
minimum: 1
description: >-
The number of intervals in a term. For example, interval=year and
interval_count=1 represents a 1 year term.
interval:
type: string
enum:
- day
- week
- month
- year
description: >-
Unit in which term duration is defined. One of day, week, month or
year.
start_date:
type: string
format: date
description: Date when the subscription term starts.
example: '2020-01-01'
type:
type: string
enum:
- evergreen
- termed
description: Type of the subscription. Can be either `termed` or `evergreen`.
end_date:
type: string
format: date
description: Date when the subscription term ends.
example: '2023-01-01'
startOn:
type: object
title: StartOn
description: >-
Container for the contract effective, service activation, and customer
acceptance dates of the order action or subscription. <ul> <li> If
[Zuora is configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for a `subscription_plans`
order action or the "Create a subscription" operation, a `pending` order
and/or a `pending_activation` subscription are created.</li> <li> If
[Zuora is configured to require customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_acceptance` subscription
are created. At the same time, if the service activation date field is
also required and not set, a `pending` order and/or a
`pending_activation` subscription are created instead.</li> <li> If
[Zuora is configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for any of the following
order actions or the "Update a subscription" operation, a `pending`
order is created. The subscription status is not impacted. **Note**:
This feature is in Limited Availability. If you want to have access to
the feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li> <li>`renew`</li>
<li>`terms`</li> </li></ul> </li> <li> If [Zuora is configured to
require customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for any of the following
order actions or the "Update a subscription" operation, a `pending`
order is created. The subscription status is not impacted. Note: This
feature is in Limited Availability. If you want to have access to the
feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li> <li>`renew`</li>
<li>`terms`</li> </li></ul>
additionalProperties: false
properties:
contract_effective:
type: string
format: date
description: >-
Effective contract date for this subscription, in the `yyyy-mm-dd`
format.
example: '2023-06-01'
service_activation:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been activated and access has been provided to the customer, as
the `yyyy-mm-dd` format. <ul> <li> If [Zuora is
configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_activation`
subscription are created.</li> <li> If [Zuora is configured
to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for any of the
following order actions or the "Update a subscription" operation, a
`pending` order is created. The subscription status is not impacted.
**Note**: This feature is in Limited Availability. If you want to
have access to the feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li>
<li>`renew`</li> <li>`terms`</li>
</ul> </li> </ul>
example: '2023-06-01'
customer_acceptance:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been accepted by the customer, in the `yyyy-mm-dd` format.
<ul> <li> If [Zuora is configured to require customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_acceptance`
subscription are created. At the same time, if the service
activation date field is also required and not set, a `pending`
order and/or a `pending_activation` subscription are created
instead.</li> <li> If [Zuora is configured to require
customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for any of the
following order actions or the "Update a subscription" operation, a
`pending` order is created. The subscription status is not impacted.
**Note**: This feature is in Limited Availability. If you want to
have access to the feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li> <li>`renew`</li>
<li>`terms`</li> </ul></li> </ul>
example: '2023-06-01'
required:
- contract_effective
subscriptionTermPatchRequest:
type: object
title: SubscriptionTermPatchRequest
description: Term information of the subscription.
additionalProperties: false
properties:
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription.
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
auto_renew:
type: boolean
description: >-
If true, the subscription automatically renews at the end of the
current term.
start_on:
$ref: '#/components/schemas/startOn'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionRemovePlanPatchRequest:
type: object
title: SubscriptionRemovePlanPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
subscription_plan_id:
type: string
description: Identifier of the subscription plan.
start_on:
$ref: '#/components/schemas/startOn'
unique_token:
type: string
description: >-
Unique identifier for the subscription plan. This identifier enables
you to refer to the subscription plan before the subscription plan
has an internal identifier in Zuora.
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionRenewPatchRequest:
type: object
title: SubscriptionRenewPatchRequest
description: Specify this field when renewing a subscription.
additionalProperties: false
properties:
start_on:
$ref: '#/components/schemas/startOn'
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionAddPlanPatchRequest:
type: object
title: SubscriptionAddPlanPatchRequest
description: ''
additionalProperties: false
properties:
subscription_plan:
$ref: '#/components/schemas/subscriptionPlanCreateRequest'
start_on:
$ref: '#/components/schemas/startOn'
change_reason:
type: string
description: A brief description of the reason for this change.
required:
- subscription_plan
subscriptionUpdatePlanPatchRequest:
type: object
title: SubscriptionUpdatePlanPatchRequest
description: ''
additionalProperties: false
properties:
subscription_plan:
$ref: '#/components/schemas/subscriptionPlanPatchRequest'
start_on:
$ref: '#/components/schemas/startOn'
start_date:
type: string
format: date
description: The start date from which this order action becomes effective.
example: '2022-01-01'
change_reason:
type: string
description: A brief description of the reason for this change.
required:
- subscription_plan
subscriptionReplacePlanPatchRequest:
type: object
title: SubscriptionReplacePlanPatchRequest
description: ''
additionalProperties: false
properties:
subscription_plan_id:
type: string
description: >-
Identifier of the subscription plan. Only provide one of
`previous_plan_id` or `subscription_plan_id` in your request, not
both.
previous_plan_id:
type: string
description: >-
Identifier of the plan to be removed. Only provide one of
`previous_plan_id` or `subscription_plan_id` in your request, not
both.
replace_at:
type: string
enum:
- now
- end_of_billing_period
- specific_date
description: "The default value for the\_`replace_at`\_field is as follows: <ul> <li>If the subscription plan change (from old to new) is an upgrade, the `replace_at` is\_`now`\_by default. </li> <li>If the subscription change (from old to new) is a downgrade, the `replace_at` is\_`end_of_billing_period`\_by default. </li> </ul> Otherwise, the `replace_at` is\_`specific_date`\_by default. **Notes**: <br /> When setting this field to\_`end_of_billing_period`, you cannot set the\_billing start dates\_for the subscription as the system will automatically set the start dates to the end of billing period, and you cannot set the following billing trigger date settings to\_`Yes`: <ul> <li> <a href=\"https://knowledgecenter.zuora.com/Zuora_Billing/Configure_billing_settings/Subscription_and_order_settings/A_Define_Default_Subscription_and_Order_Settings#Require_Customer_Acceptance_of_Orders.3F\" target=\"_blank\">Require Customer Acceptance of Orders</a> </li> <li> <a href=\"https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Default_Subscription_and_Order_Settings#Require_Service_Activation_of_Orders.3F\" target=\"_blank\">Require Service Activation of Orders</a> </li> </ul> When setting this field to\_`specific_date`, you must also specify a date for the `contract_effective` date in the\_`start_on`\_field. "
replacement_type:
type: string
enum:
- upgrade
- downgrade
- crossgrade
- other
subscription_plan:
$ref: '#/components/schemas/subscriptionPlanCreateRequest'
start_on:
$ref: '#/components/schemas/startOn'
change_reason:
type: string
description: A brief description of the reason for this change.
required:
- subscription_plan
pauseSubscriptionRequest:
type: object
title: PauseSubscriptionRequest
description: ''
nullable: true
additionalProperties: false
properties:
pause_date:
type: string
x-zuora-field-type: date
description: Date on which the subscription is paused.
pause_at:
type: string
enum:
- invoice_period_end
description: >-
Can be either the end of the current billing period or a specific
date.
pause_interval_count:
type: number
description: >-
The number of intervals in a duration where the subscription is
paused. For example, pause_interval=year and pause_interval_count=1
represents a 1-year pause.
pause_interval:
type: string
enum:
- month
- day
- year
- week
description: >-
Unit in which the pause duration is defined. One of day, week, month
or year.
change_reason:
type: string
description: A brief description of the reason for this change.
resume_behavior:
$ref: '#/components/schemas/resumeSubscriptionRequest'
custom_fields:
$ref: '#/components/schemas/customFields'
resumeSubscriptionRequest:
type: object
title: ResumeSubscriptionRequest
description: Behavior of the paused subscription when it resumes.
additionalProperties: false
properties:
extend_term:
type: boolean
default: false
description: >-
If this field is set to `true`, the subscription term is extended by
the length of time the subscription is paused.
resume_date:
type: string
x-zuora-field-type: date
description: Date on which the paused subscription is resumed.
resume_at:
type: string
enum:
- pause_date
description: >-
You can use this field to resume a paused subscription from the
pause date.
change_reason:
type: string
description: A brief description of the reason for this change.
custom_fields:
$ref: '#/components/schemas/customFields'
cancelSubscriptionRequest:
type: object
title: CancelSubscriptionRequest
description: ''
nullable: false
additionalProperties: false
properties:
cancel_date:
type: string
x-zuora-field-type: date
description: Date on which the subscription is canceled.
cancel_at:
type: string
enum:
- invoice_period_end
- subscription_term_end
description: >-
The date on which the subscription is canceled. Can be either the
end of the subscription term or the end of the billing period.
processing_options:
allOf:
- $ref: '#/components/schemas/processingOptions'
description: Processing options for the invoice or payment.
refund_amount:
type: number
description: Amount to be refunded
write_off:
type: boolean
default: false
description: >-
Indicates whether to write off the outstanding balance on the
invoice after canceling the subscription.
write_off_behavior:
$ref: '#/components/schemas/writeOffSuscriptionRequest'
custom_fields:
$ref: '#/components/schemas/customFields'
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionCreateRequest:
type: object
title: SubscriptionCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription. If you specify this field, do not specify
`invoice_owner_account_data`.
invoice_owner_account_number:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription. If you specify this field, do not specify
`invoice_owner_account_data`.
invoice_owner_account_data:
allOf:
- $ref: '#/components/schemas/accountCreateRequest'
description: >-
The information of the new account that owns the invoice associated
with this subscription. If you specify this field, do not specify
`invoice_owner_account_id`.
account_id:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_number:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_data:
allOf:
- $ref: '#/components/schemas/accountCreateRequest'
description: >-
The information of the new account that owns the subscription. The
subscription owner account can be different from the invoice owner
account. If you specify this field, do not specify `account_id`.
auto_renew:
type: boolean
description: >-
If true, the subscription automatically renews at the end of the
current term.
subscription_number:
type: string
description: Human-readable identifier of the subscription; maybe user-supplied.
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription
start_on:
$ref: '#/components/schemas/startOn'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
invoice_separately:
type: boolean
description: >-
Separates a single subscription from other subscriptions and creates
an invoice for this subscription. If the value is `true`, the
subscription is billed separately from other subscriptions. If the
value is `false`, the subscription is included with other
subscriptions in the account invoice.
processing_options:
$ref: '#/components/schemas/processingOptions'
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionPlanCreateRequest'
description: The plans associated with the new subscription.
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
change_reason:
type: string
description: A brief description of the reason for this change.
subscription:
type: object
title: Subscription
description: Subscription information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
state:
type: string
enum:
- draft
- pending_activation
- pending_acceptance
- active
- expired
- canceled
- paused
description: Status of the subscription.
version:
type: integer
description: >-
The version of the subscription. This version can be used in the
`filter[]` query parameter to filter subscriptions.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
invoice_owner_account:
allOf:
- $ref: '#/components/schemas/account'
description: Identifier of the account that owns the subscription.
auto_renew:
type: boolean
description: >-
If this field is set to `true`, the subscription automatically
renews at the end of the current term.
latest_version:
type: boolean
description: If true, this is the latest version of the subscription
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
start_date:
type: string
format: date
description: Date when the subscription starts.
example: '2020-01-01'
end_date:
type: string
format: date
description: Date when the subscription ends.
example: '2023-01-01'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
contract_effective:
type: string
format: date
description: Date when the subscriber contract is effective.
example: '2023-01-01'
service_activation:
type: string
format: date
description: Date when the subscribed-to service is activated.
example: '2023-01-01'
customer_acceptance:
type: string
format: date
description: >-
Date when all the services or products in the subscription are
accepted by the subscriber.
example: '2023-01-01'
invoice_separately:
type: boolean
description: >-
If true, the subscription is billed separately from other
subscriptions. If false, the subscription is included with other
subscriptions in the account invoice. The default is false.
order_number:
type: string
description: The order number of the order created by Zuora.
subscription_plans:
allOf:
- $ref: '#/components/schemas/subscriptionPlanListResponse'
readOnly: true
description: List of subscription plans.
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items.
prepaid_balance:
type: array
items:
$ref: '#/components/schemas/prepaidBalance'
readOnly: true
deprecated: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription. **Deprecated, please
use `prepaid_balances` instead.**
prepaid_balances:
type: array
items:
$ref: '#/components/schemas/prepaidBalances'
readOnly: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription.
contracted_mrr:
type: string
description: Monthly recurring revenue of the subscription.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
cancel_reason:
type: string
description: The reason for cancelling the subscription.
last_booking_date:
type: string
format: date
description: >-
The last booking date of the subscription object. You can override
the date value when creating a subscription through the "Subscribe
and Amend" API. The default value `today` is set per the user's
timezone. The value of this field is as follows: <ul> <li>For
a new subscription created by the [Subscribe and
Amend](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate)
APIs, this field has the value of the subscription creation date.
</li> <li>For a subscription changed by an amendment, this field
has the value of the amendment booking date.</li> <li>For a
subscription created or changed by an order, this field has the
value of the order date.</li> </ul>
example: '2023-01-01'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
subscriptionPatchRequest:
type: object
title: SubscriptionPatchRequest
description: ''
nullable: true
additionalProperties: false
properties:
description:
type: string
description: Description of the subscription.
custom_fields:
$ref: '#/components/schemas/customFields'
terms:
$ref: '#/components/schemas/subscriptionTermPatchRequest'
start_on:
$ref: '#/components/schemas/startOn'
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
invoice_owner_account_number:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
account_id:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account.
account_number:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account.
add_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionAddPlanPatchRequest'
description: >-
Specify this field if you want to add one or multiple subscription
plans to this subscription.
remove_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionRemovePlanPatchRequest'
description: >-
Specify this field if you want to remove one or multiple
subscription plans from this subscription.
replace_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionReplacePlanPatchRequest'
description: >-
Specify this field if you want to replace one or multiple
subscription plans to this subscription. <br /> **Note**:
This field is currently not supported if you have Billing - Revenue
Integration enabled. When Billing - Revenue Integration is enabled,
the replace subscription plan type of order action will no longer be
applicable in Zuora Billing.
update_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionUpdatePlanPatchRequest'
renew:
$ref: '#/components/schemas/subscriptionRenewPatchRequest'
renewals:
type: array
items:
$ref: '#/components/schemas/subscriptionRenewPatchRequest'
description: Specify this field when renewing a subscription.
cancel:
$ref: '#/components/schemas/cancelSubscriptionRequest'
pause:
$ref: '#/components/schemas/pauseSubscriptionRequest'
resume:
$ref: '#/components/schemas/resumeSubscriptionRequest'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_separately:
type: boolean
description: >-
Separates a single subscription from other subscriptions and creates
an invoice for this subscription. If the value is `true`, the
subscription is billed separately from other subscriptions. If the
value is `false`, the subscription is included with other
subscriptions in the account invoice.
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionActivateRequest:
type: object
title: SubscriptionActivateRequest
description: ''
nullable: true
additionalProperties: false
properties:
contract_effective:
type: string
format: date
description: >-
Effective contract date for this subscription, in the `yyyy-mm-dd`
format.
example: '2023-06-01'
service_activation:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been activated and access has been provided to the customer, as
the `yyyy-mm-dd` format. <ul> <li> If [Zuora is
configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_activation`
subscription are created.</li> <li> If [Zuora is configured
to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for any of the
following order actions or the "Update a subscription" operation, a
`pending` order is created. The subscription status is not impacted.
**Note**: This feature is in Limited Availability. If you want to
have access to the feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li>
<li>`renew`</li> <li>`terms`</li>
</ul> </li> </ul>
example: '2023-06-01'
customer_acceptance:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been accepted by the customer, in the `yyyy-mm-dd` format.
<ul> <li> If [Zuora is configured to require customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_acceptance`
subscription are created. At the same time, if the service
activation date field is also required and not set, a `pending`
order and/or a `pending_activation` subscription are created
instead.</li> <li> If [Zuora is configured to require
customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for any of the
following order actions or the "Update a subscription" operation, a
`pending` order is created. The subscription status is not impacted.
**Note**: This feature is in Limited Availability. If you want to
have access to the feature, submit a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li> <li>`renew`</li>
<li>`terms`</li> </ul></li> </ul>
example: '2023-06-01'
subscriptionListResponse:
type: object
title: SubscriptionListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/subscription'
postSubscriptionOrderRequest:
type: object
title: PostSubscriptionOrderRequest
description: ''
nullable: false
additionalProperties: false
properties:
account_number:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_id:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_data:
allOf:
- $ref: '#/components/schemas/accountCreateRequest'
description: >-
The information of the new account that owns the subscription. The
subscription owner account can be different from the invoice owner
account. If you specify this field, do not specify `account_id`.
invoice_owner_account_number:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription. If you specify this field, do not specify
`invoice_owner_account_data`.
auto_renew:
type: boolean
description: >-
If true, the subscription automatically renews at the end of the
current term.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. If an existing
`subscription_number` is supplied, the order will update that
subscription. Meanwhile, if the specified `subscription_number` does
not exist in the tenant, it will instead create a new one
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription
start_on:
$ref: '#/components/schemas/startOn'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
invoice_separately:
type: boolean
description: >-
Separates a single subscription from other subscriptions and creates
an invoice for this subscription. If the value is `true`, the
subscription is billed separately from other subscriptions. If the
value is `false`, the subscription is included with other
subscriptions in the account invoice.
processing_options:
$ref: '#/components/schemas/processingOptions'
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionPlanCreateRequest'
description: The plans associated with the new subscription.
add_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionAddPlanPatchRequest'
description: >-
Specify this field if you want to add one or multiple subscription
plans to this subscription.
remove_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionRemovePlanPatchRequest'
description: >-
Specify this field if you want to remove one or multiple
subscription plans from this subscription.
update_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionUpdatePlanPatchRequest'
renew:
$ref: '#/components/schemas/subscriptionRenewPatchRequest'
renewals:
type: array
items:
$ref: '#/components/schemas/subscriptionRenewPatchRequest'
description: Specify this field when renewing a subscription.
cancel:
$ref: '#/components/schemas/cancelSubscriptionRequest'
pause:
$ref: '#/components/schemas/pauseSubscriptionRequest'
resume:
$ref: '#/components/schemas/resumeSubscriptionRequest'
replace_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionReplacePlanPatchRequest'
description: >-
Specify this field if you want to replace one or multiple
subscription plans to this subscription. <br /> **Note**:
This field is currently not supported if you have Billing - Revenue
Integration enabled. When Billing - Revenue Integration is enabled,
the replace subscription plan type of order action will no longer be
applicable in Zuora Billing.
terms:
$ref: '#/components/schemas/subscriptionTermPatchRequest'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
change_reason:
type: string
description: A brief description of the reason for this change.
subscriptionPreviewAccountRequest:
type: object
title: SubscriptionPreviewAccountRequest
description: >-
Account data that is used for the subscription preview. If you specify
this field, do not specify `account_id`. Note that this operation is
only for preview and no subscription is created.
additionalProperties: false
properties:
sold_to:
allOf:
- $ref: '#/components/schemas/accountContactCreateRequest'
description: Customer address used for calculating tax.
tax_certificate:
$ref: '#/components/schemas/taxCertificate'
bill_cycle_day:
type: integer
minimum: 0
maximum: 31
description: >-
The day of the month on which your customer will be invoiced. For
month-end specify 31.
currency:
type: string
description: >-
Three-letter ISO currency code. Once the currency is set for an
account, it cannot be updated.
example: USD
tax_identifier:
$ref: '#/components/schemas/taxIdentifier'
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- bill_cycle_day
- currency
subscriptionPreviewRequest:
type: object
title: SubscriptionPreviewRequest
description: ''
nullable: false
additionalProperties: false
properties:
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription. If you specify this field, do not specify
`invoice_owner_account_data`.
invoice_owner_account_number:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription. If you specify this field, do not specify
`invoice_owner_account_data`.
invoice_owner_account_data:
allOf:
- $ref: '#/components/schemas/accountCreateRequest'
description: >-
The information of the new account that owns the invoice associated
with this subscription. If you specify this field, do not specify
`invoice_owner_account_id`.
account_id:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_number:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account. If
you specify this field, do not specify `account_data`.
account_data:
$ref: '#/components/schemas/subscriptionPreviewAccountRequest'
auto_renew:
type: boolean
description: >-
If true, the subscription automatically renews at the end of the
current term.
subscription_number:
type: string
description: Human-readable identifier of the subscription; maybe user-supplied.
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription
start_on:
$ref: '#/components/schemas/startOn'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
invoice_separately:
type: boolean
description: >-
Separates a single subscription from other subscriptions and creates
an invoice for this subscription. If the value is `true`, the
subscription is billed separately from other subscriptions. If the
value is `false`, the subscription is included with other
subscriptions in the account invoice.
processing_options:
$ref: '#/components/schemas/processingOptions'
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionPlanCreateRequest'
description: The plans associated with the new subscription.
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
change_reason:
type: string
description: A brief description of the reason for this change.
number_of_periods:
type: integer
description: Specifies how many billing periods you want to preview.
term_end:
type: boolean
description: >-
Indicates whether to preview the subscription till the end of the
current term.
metrics:
type: array
items:
type: string
enum:
- billing_documents
- delta_metrics
description: >-
Specifies the metrics you want to preview. You can preivew
metrics of billing documents, the order delta metrics, or both.
end_date:
type: string
format: date
description: >-
End date of the period for which you want to preview the
subscription
subscriptionItemPreviewResponse:
type: object
title: SubscriptionItemPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
subscription_item_id:
type: string
description: Identifier of the subscription item.
price_id:
type: string
description: Identifier of the price.
start_date:
type: string
format: date
description: Date on which the subscription item starts to become effective.
end_date:
type: string
format: date
description: Date on which the subscription item expires.
mrr:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
tcb:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
tcv:
type: object
properties:
gross_amount:
type: number
net_amount:
type: number
currency:
type: string
subscriptionPreviewActionsResponse:
type: object
title: SubscriptionPreviewActionsResponse
description: ''
nullable: false
additionalProperties: false
properties:
action_id:
type: string
description: Identifier of the action.
action:
type: string
enum:
- create_subscription
- terms
- add_subscription_plan
- update_subscription_plan
- remove_subscription_plan
- renew
- cancel
- owner_transfer
- pause
- resume
- replace_subscription_plan
description: The action associated with this metric.
sequence:
type: integer
description: The sequence number of the action.
subscription_items:
type: array
items:
allOf:
- $ref: '#/components/schemas/subscriptionItemPreviewResponse'
subscriptionPreviewResponse:
type: object
title: SubscriptionPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
actions:
type: array
items:
allOf:
- $ref: '#/components/schemas/subscriptionPreviewActionsResponse'
billing_documents:
type: array
items:
allOf:
- $ref: >-
#/components/schemas/subscriptionPreviewBillingDocumentsResponse
subscriptionPreviewBillingDocumentItemResponse:
type: object
title: SubscriptionPreviewBillingDocumentItemResponse
description: ''
nullable: false
additionalProperties: false
properties:
subscription_item_description:
type: string
subscription_item_name:
type: string
subscription_item_number:
type: string
processing_type:
type: string
enum:
- subscription_item
- discount
- prepayment
- tax
product_name:
type: string
price_id:
type: string
description: >-
The identifier of the price this billing document item is associated
with.
service_end_date:
type: string
description: >-
The end date of the service period associated with this billing
document item. If the associated charge is a one-time fee, then this
date is the date of that charge.
service_start_date:
type: string
description: >-
The start date of the service period associated with this billing
document item. If the associated charge is a one-time fee, then this
date is the date of that charge.
tax:
type: number
description: The amount of tax applied to the billing document item.
quantity:
type: number
description: The number of units of this item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
subtotal:
type: number
description: The total amount of this billing document item exclusive of tax.
total:
type: number
description: The total amount of this billing document item.
taxation_items:
type: array
items:
allOf:
- $ref: >-
#/components/schemas/subscriptionPreviewBillingDocumentTaxationItemResponse
subscriptionPreviewBillingDocumentTaxationItemResponse:
type: object
title: SubscriptionPreviewBillingDocumentTaxationItemResponse
description: ''
nullable: false
additionalProperties: false
properties:
amount_exempt:
type: number
description: The calculated tax amount excluded due to the exemption.
id:
type: string
description: >-
Identifier of the taxation item related to the invoice. Only
applicable for credit memos created from invoices.
jurisdiction:
type: string
maxLength: 32
description: >-
The jurisdiction that applies the tax or VAT. This value is
typically a state, province, county, or city.
location_code:
type: string
maxLength: 32
description: >-
The identifier for the location based on the value of the `tax_code`
field.
name:
type: string
maxLength: 128
description: The name of the taxation item.
amount:
type: number
description: The amount of the tax applied to the total price.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not provided
when you create or update a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_code_name:
type: string
description: The amount of the tax applied to the total price.
date:
type: string
format: date
description: The date on which the tax is applied.
example: '2022-01-01'
tax_rate:
type: number
description: The amount of the tax applied to the total price.
tax_rate_name:
type: string
description: >-
The name of the tax rate, such as sales tax or GST. This name is
displayed on billing documents.
tax_rate_type:
type: string
enum:
- percent
- amount
description: Indicates whether the tax rate is an amount or a percentage.
subscriptionPreviewBillingDocumentsResponse:
type: object
title: SubscriptionPreviewBillingDocumentsResponse
description: ''
nullable: false
additionalProperties: false
properties:
subtotal:
type: number
readOnly: true
description: The total amount exclusive of tax.
tax:
type: number
readOnly: true
description: The total tax amount.
total:
type: number
readOnly: true
description: The total amount.
type:
type: string
enum:
- credit_memo
- debit_memo
- invoice
description: >-
The type of billing document. Can be one of the credit memo, debit
memo, or invoice.
target_date:
type: string
format: date
billing_document_items:
type: array
items:
allOf:
- $ref: >-
#/components/schemas/subscriptionPreviewBillingDocumentItemResponse
subscriptionPreviewExistingRequest:
type: object
title: SubscriptionPreviewExistingRequest
description: ''
nullable: false
additionalProperties: false
properties:
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: Description of the subscription.
account_id:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account.
account_number:
type: string
description: >-
Identifier of the account that owns the subscription. Subscription
owner account can be different from the invoice owner account.
account_data:
$ref: '#/components/schemas/subscriptionPreviewAccountRequest'
number_of_periods:
type: integer
description: Specifies how many billing periods you want to preview.
term_end:
type: boolean
description: >-
Indicates whether to preview the subscription till the end of the
current term.
metrics:
type: array
items:
type: string
enum:
- billing_documents
- delta_metrics
description: >-
Specifies the metrics you want to preview. You can preview
metrics of billing documents, the order delta metrics, or both.
end_date:
type: string
format: date
description: >-
End date of the period for which you want to preview the
subscription
add_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionAddPlanPatchRequest'
description: >-
Specify this field if you want to add one or multiple subscription
plans to this subscription.
replace_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionReplacePlanPatchRequest'
description: >-
Specify this field if you want to replace one or multiple
subscription plans to this subscription. <br /> **Note**:
This field is currently not supported if you have Billing - Revenue
Integration enabled. When Billing - Revenue Integration is enabled,
the replace subscription plan type of order action will no longer be
applicable in Zuora Billing.
update_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionUpdatePlanPatchRequest'
remove_subscription_plans:
type: array
items:
$ref: '#/components/schemas/subscriptionRemovePlanPatchRequest'
description: >-
Specify this field if you want to remove one or multiple
subscription plans from this subscription.
orderActionListResponse:
type: object
title: OrderActionListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/orderAction'
subscriptionVersion:
type: object
title: SubscriptionVersion
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
state:
type: string
enum:
- draft
- pending_activation
- pending_acceptance
- active
- expired
- canceled
- paused
description: Status of the subscription.
version:
type: integer
description: >-
The version of the subscription. This version can be used in the
`filter[]` query parameter to filter subscriptions.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
invoice_owner_account:
allOf:
- $ref: '#/components/schemas/account'
description: Identifier of the account that owns the subscription.
auto_renew:
type: boolean
description: >-
If this field is set to `true`, the subscription automatically
renews at the end of the current term.
latest_version:
type: boolean
description: If true, this is the latest version of the subscription
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
start_date:
type: string
format: date
description: Date when the subscription starts.
example: '2020-01-01'
end_date:
type: string
format: date
description: Date when the subscription ends.
example: '2023-01-01'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
contract_effective:
type: string
format: date
description: Date when the subscriber contract is effective.
example: '2023-01-01'
service_activation:
type: string
format: date
description: Date when the subscribed-to service is activated.
example: '2023-01-01'
customer_acceptance:
type: string
format: date
description: >-
Date when all the services or products in the subscription are
accepted by the subscriber.
example: '2023-01-01'
invoice_separately:
type: boolean
description: >-
If true, the subscription is billed separately from other
subscriptions. If false, the subscription is included with other
subscriptions in the account invoice. The default is false.
order_number:
type: string
description: The order number of the order created by Zuora.
subscription_plans:
allOf:
- $ref: '#/components/schemas/subscriptionPlanListResponse'
readOnly: true
description: List of subscription plans.
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items.
prepaid_balance:
type: array
items:
$ref: '#/components/schemas/prepaidBalance'
readOnly: true
deprecated: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription. **Deprecated, please
use `prepaid_balances` instead.**
prepaid_balances:
type: array
items:
$ref: '#/components/schemas/prepaidBalances'
readOnly: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription.
contracted_mrr:
type: string
description: Monthly recurring revenue of the subscription.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
cancel_reason:
type: string
description: The reason for cancelling the subscription.
last_booking_date:
type: string
format: date
description: >-
The last booking date of the subscription object. You can override
the date value when creating a subscription through the "Subscribe
and Amend" API. The default value `today` is set per the user's
timezone. The value of this field is as follows: <ul> <li>For
a new subscription created by the [Subscribe and
Amend](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate)
APIs, this field has the value of the subscription creation date.
</li> <li>For a subscription changed by an amendment, this field
has the value of the amendment booking date.</li> <li>For a
subscription created or changed by an order, this field has the
value of the order date.</li> </ul>
example: '2023-01-01'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
actions:
allOf:
- $ref: '#/components/schemas/orderActionListResponse'
order:
allOf:
- $ref: '#/components/schemas/subscriptionVersionOrder'
subscriptionVersionListResponse:
type: object
title: SubscriptionVersionListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/subscriptionVersion'
refundTransactions:
type: object
title: RefundTransactions
description: ''
nullable: false
additionalProperties: false
properties:
refund_number:
type: string
invoice_numbers:
type: array
items:
type: string
state:
allOf:
- type: object
properties:
succeeded:
type: string
readOnly: true
failed:
type: string
readOnly: true
refunds:
allOf:
- $ref: '#/components/schemas/refund'
description: The related invoices.
paymentTransactions:
type: object
title: PaymentTransactions
description: ''
nullable: false
additionalProperties: false
properties:
payment_number:
type: string
description: The number of the payment.
amount:
type: array
items:
type: string
description: The payment transaction amount.
state:
allOf:
- type: object
properties:
succeeded:
type: string
readOnly: true
failed:
type: string
readOnly: true
description: The state of the payment.
payments:
allOf:
- $ref: '#/components/schemas/payment'
description: The related payments.
arTransactions:
type: object
title: ArTransactions
description: ''
nullable: false
additionalProperties: false
properties:
credit_memo_numbers:
type: array
items:
type: string
description: Credit memo numbers.
credit_memos:
allOf:
- $ref: '#/components/schemas/creditMemo'
description: The related credit memos.
invoice_numbers:
type: array
items:
type: string
description: The related invoice numbers.
invoices:
allOf:
- $ref: '#/components/schemas/invoice'
description: The related invoices.
refunds:
type: array
items:
$ref: '#/components/schemas/refundTransactions'
description: The related refunds.
payments:
type: array
items:
$ref: '#/components/schemas/paymentTransactions'
description: The related payments.
writeOff:
type: object
title: WriteOff
description: ''
nullable: false
additionalProperties: false
properties:
amount:
type: string
description: The total billing document amount that is written off.
failed_reason:
type: string
description: Reasons for failure.
invoice_number:
type: string
description: The invoice number.
invoice:
allOf:
- $ref: '#/components/schemas/invoice'
description: The related invoice.
state:
allOf:
- type: object
properties:
succeeded:
type: string
readOnly: true
failed:
type: string
readOnly: true
description: The states of the transactions.
credit_memo_number:
type: string
description: The credit memo number.
subscriptionCancelResponse:
type: object
title: SubscriptionCancelResponse
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
state:
type: string
enum:
- draft
- pending_activation
- pending_acceptance
- active
- expired
- canceled
- paused
description: Status of the subscription.
version:
type: integer
description: >-
The version of the subscription. This version can be used in the
`filter[]` query parameter to filter subscriptions.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
invoice_owner_account:
allOf:
- $ref: '#/components/schemas/account'
description: Identifier of the account that owns the subscription.
auto_renew:
type: boolean
description: >-
If this field is set to `true`, the subscription automatically
renews at the end of the current term.
latest_version:
type: boolean
description: If true, this is the latest version of the subscription
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
start_date:
type: string
format: date
description: Date when the subscription starts.
example: '2020-01-01'
end_date:
type: string
format: date
description: Date when the subscription ends.
example: '2023-01-01'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
contract_effective:
type: string
format: date
description: Date when the subscriber contract is effective.
example: '2023-01-01'
service_activation:
type: string
format: date
description: Date when the subscribed-to service is activated.
example: '2023-01-01'
customer_acceptance:
type: string
format: date
description: >-
Date when all the services or products in the subscription are
accepted by the subscriber.
example: '2023-01-01'
invoice_separately:
type: boolean
description: >-
If true, the subscription is billed separately from other
subscriptions. If false, the subscription is included with other
subscriptions in the account invoice. The default is false.
order_number:
type: string
description: The order number of the order created by Zuora.
subscription_plans:
allOf:
- $ref: '#/components/schemas/subscriptionPlanListResponse'
readOnly: true
description: List of subscription plans.
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items.
prepaid_balance:
type: array
items:
$ref: '#/components/schemas/prepaidBalance'
readOnly: true
deprecated: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription. **Deprecated, please
use `prepaid_balances` instead.**
prepaid_balances:
type: array
items:
$ref: '#/components/schemas/prepaidBalances'
readOnly: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription.
contracted_mrr:
type: string
description: Monthly recurring revenue of the subscription.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
cancel_reason:
type: string
description: The reason for cancelling the subscription.
last_booking_date:
type: string
format: date
description: >-
The last booking date of the subscription object. You can override
the date value when creating a subscription through the "Subscribe
and Amend" API. The default value `today` is set per the user's
timezone. The value of this field is as follows: <ul> <li>For
a new subscription created by the [Subscribe and
Amend](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate)
APIs, this field has the value of the subscription creation date.
</li> <li>For a subscription changed by an amendment, this field
has the value of the amendment booking date.</li> <li>For a
subscription created or changed by an order, this field has the
value of the order date.</li> </ul>
example: '2023-01-01'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
ar_transactions:
allOf:
- $ref: '#/components/schemas/arTransactions'
readOnly: true
write_offs:
type: array
items:
$ref: '#/components/schemas/writeOff'
readOnly: true
description: The billing documents that are written off.
subscriptionTermPatchResponse:
type: object
title: SubscriptionTermPatchResponse
description: Term information of the subscription.
additionalProperties: false
properties:
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription.
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
auto_renew:
type: boolean
description: >-
If true, the subscription automatically renews at the end of the
current term.
subscriptionAddPlanPatchResponse:
type: object
title: SubscriptionAddPlanPatchResponse
description: ''
nullable: false
additionalProperties: false
properties:
unique_token:
type: string
description: >-
A unique string to represent the subscription plan in the order. The
unique token is used to perform multiple actions against a newly
added subscription plan. For example, if you want to add and update
a product in the same order, assign a unique token to the newly
added subscription plan and use that token in future order actions.
plan_id:
type: string
description: >-
The id of the subscription plan to be updated. It can be the latest
version or any history version id.
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_items:
allOf:
- $ref: '#/components/schemas/subscriptionItemListResponse'
subscriptionRemovePlanPatchResponse:
type: object
title: SubscriptionRemovePlanPatchResponse
description: ''
nullable: false
additionalProperties: false
properties:
subscription_plan_id:
type: string
description: Identifier of the subscription plan.
subscriptionRenewPatchResponse:
type: object
title: SubscriptionRenewPatchResponse
description: Specify this field to renew a subscription
additionalProperties: false
properties:
terms:
allOf:
- $ref: '#/components/schemas/subscriptionTermPatchResponse'
subscriptionUpdatePlanPatchResponse:
type: object
title: SubscriptionUpdatePlanPatchResponse
description: ''
nullable: false
additionalProperties: false
properties:
unique_token:
type: string
description: >-
A unique string to represent the subscription plan in the order. The
unique token is used to perform multiple actions against a newly
added subscription plan. For example, if you want to add and update
a product in the same order, assign a unique token to the newly
added subscription plan and use that token in future order actions.
plan_id:
type: string
description: >-
The id of the subscription plan to be updated. It can be the latest
version or any history version id.
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_items:
allOf:
- $ref: '#/components/schemas/subscriptionItemListResponse'
subscriptionCancelPatchResponse:
type: object
title: SubscriptionCancelPatchResponse
description: Specify this field to cancel a subscription
additionalProperties: false
properties:
cancel_date:
type: string
format: date
description: Date on which the subscription is canceled.
example: '2022-06-01'
cancel_at:
type: string
enum:
- invoice_period_end
- subscription_term_end
description: >-
The date on which the subscription is canceled. Can be either the
end of the subscription term or the end of the billing period.
subscriptionReplacePlanPatchResponse:
type: object
title: SubscriptionReplacePlanPatchResponse
description: ''
nullable: false
additionalProperties: false
properties:
previous_subscription_plan_id:
type: string
description: Identifier of the subscription plan.
previous_plan_id:
type: string
description: >-
Identifier of the plan to be removed. Only provide one of
`previous_plan_id` or `subscription_plan_id` in your request, not
both.
replace_at:
type: string
enum:
- now
- end_of_billing_period
- specific_date
description: >-
The date when the replacement occurs. It can be either the current
date or the end of the current billing period.
replacement_type:
type: string
enum:
- upgrade
- downgrade
- crossgrade
- other
description: The type of the replacement.
unique_token:
type: string
description: >-
A unique string to represent the subscription plan in the order. The
unique token is used to perform multiple actions against a newly
added subscription plan. For example, if you want to add and update
a product in the same order, assign a unique token to the newly
added subscription plan and use that token in future order actions.
plan_id:
type: string
description: >-
The id of the subscription plan to be updated. It can be the latest
version or any history version id.
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_items:
allOf:
- $ref: '#/components/schemas/subscriptionItemListResponse'
subscriptionPausePatchResponse:
type: object
title: SubscriptionPausePatchResponse
description: Specify this field if you want to pause a subscription.
additionalProperties: false
properties:
pause_date:
type: string
x-zuora-field-type: date
description: Date on which the subscription is paused.
pause_at:
type: string
enum:
- invoice_period_end
description: >-
Can be either the end of the current billing period or a specific
date.
pause_interval_count:
type: number
description: >-
The number of intervals in a duration where the subscription is
paused. For example, pause_interval=year and pause_interval_count=1
represents a 1-year pause.
pause_interval:
type: string
enum:
- month
- day
- year
- week
description: >-
Unit in which the pause duration is defined. One of day, week, month
or year.
change_reason:
type: string
description: A brief description of the reason for this change.
resume_behavior:
$ref: '#/components/schemas/resumeSubscriptionRequest'
custom_fields:
$ref: '#/components/schemas/customFields'
subscriptionResumePatchResponse:
type: object
title: SubscriptionResumePatchResponse
description: Specify this field if you want to resume a subscription.
additionalProperties: false
properties:
extend_term:
type: boolean
default: false
description: >-
If this field is set to `true`, the subscription term is extended by
the length of time the subscription is paused.
resume_date:
type: string
x-zuora-field-type: date
description: Date on which the paused subscription is resumed.
resume_at:
type: string
enum:
- pause_date
description: >-
You can use this field to resume a paused subscription from the
pause date.
change_reason:
type: string
description: A brief description of the reason for this change.
custom_fields:
$ref: '#/components/schemas/customFields'
orderAction:
type: object
title: OrderAction
description: ''
nullable: false
additionalProperties: false
properties:
action_id:
type: string
description: Identifier of the action.
type:
type: string
enum:
- create_subscription
- terms
- add_subscription_plan
- update_subscription_plan
- remove_subscription_plan
- renew
- cancel
- owner_transfer
- pause
- resume
- replace_subscription_plan
description: The action associated with this metric.
sequence:
type: integer
description: The sequence number of the action.
start_on:
type: object
title: StartOnResponse
description: Indicates on which date the subscription becomes effective.
additionalProperties: false
properties:
contract_effective:
type: string
format: date
description: >-
Effective contract date for this subscription, in the
`yyyy-mm-dd` format.
example: '2023-06-01'
service_activation:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been activated and access has been provided to the
customer, as the `yyyy-mm-dd` format. <ul> <li> If
[Zuora is configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_activation`
subscription are created.</li> <li> If [Zuora is
configured to require service
activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F)
and the `service_activation` field is not set for any of the
following order actions or the "Update a subscription"
operation, a `pending` order is created. The subscription status
is not impacted. **Note**: This feature is in Limited
Availability. If you want to have access to the feature, submit
a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li>
<li>`renew`</li> <li>`terms`</li>
</ul> </li> </ul>
example: '2023-06-01'
customer_acceptance:
type: string
format: date
description: >-
The date on which the services or products within a subscription
have been accepted by the customer, in the `yyyy-mm-dd`
format. <ul> <li> If [Zuora is configured to require
customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for a
`subscription_plans` order action or the "Create a subscription"
operation, a `pending` order and/or a `pending_acceptance`
subscription are created. At the same time, if the service
activation date field is also required and not set, a `pending`
order and/or a `pending_activation` subscription are created
instead.</li> <li> If [Zuora is configured to
require customer
acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F)
and the `customer_acceptance` field is not set for any of the
following order actions or the "Update a subscription"
operation, a `pending` order is created. The subscription status
is not impacted. **Note**: This feature is in Limited
Availability. If you want to have access to the feature, submit
a request at [Zuora Global
Support](https://support.zuora.com/). <ul>
<li>`add_subscription_plans`</li>
<li>`update_subscription_plans`</li>
<li>`remove_subscription_plans`</li>
<li>`renew`</li> <li>`terms`</li> </ul></li>
</ul>
example: '2023-06-01'
subscription_plans:
allOf:
- $ref: '#/components/schemas/subscriptionPlanListResponse'
description: Specify this field to add new plans to the new subscription.
add_subscription_plan:
allOf:
- $ref: '#/components/schemas/subscriptionAddPlanPatchResponse'
description: >-
Specify this field to add subscription plans to existing
subscriptions.
remove_subscription_plan:
allOf:
- $ref: '#/components/schemas/subscriptionRemovePlanPatchResponse'
description: >-
Specify this field to remove subscription plans from existing
subscriptions.
update_subscription_plan:
allOf:
- $ref: '#/components/schemas/subscriptionUpdatePlanPatchResponse'
description: >-
Specify this field to update subscription plans on the existing
subscriptions.
replace_subscription_plan:
allOf:
- $ref: '#/components/schemas/subscriptionReplacePlanPatchResponse'
description: >-
Specify this field to replace existing subscription plans with new
plans.
renew:
allOf:
- $ref: '#/components/schemas/subscriptionRenewPatchResponse'
description: Specify this field to renew an existing subscription.
terms:
allOf:
- $ref: '#/components/schemas/subscriptionTermPatchResponse'
cancel:
allOf:
- $ref: '#/components/schemas/subscriptionCancelPatchResponse'
description: Specify this field to cancel an existing subscription.
pause:
allOf:
- $ref: '#/components/schemas/subscriptionPausePatchResponse'
description: Specify this field to pause an existing subscription.
resume:
allOf:
- $ref: '#/components/schemas/subscriptionResumePatchResponse'
description: Specify this field to resume a paused subscription.
postSubscriptionOrderResponse:
type: object
title: PostSubscriptionOrderResponse
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
state:
type: string
enum:
- draft
- pending_activation
- pending_acceptance
- active
- expired
- canceled
- paused
description: Status of the subscription.
version:
type: integer
description: >-
The version of the subscription. This version can be used in the
`filter[]` query parameter to filter subscriptions.
account_id:
type: string
description: Identifier of the account associated with this subscription.
account:
allOf:
- $ref: '#/components/schemas/account'
description: Information of the new account associated with the subscription.
invoice_owner_account_id:
type: string
description: >-
Identifier of the account that owns the invoice associated with this
subscription.
invoice_owner_account:
allOf:
- $ref: '#/components/schemas/account'
description: Identifier of the account that owns the subscription.
auto_renew:
type: boolean
description: >-
If this field is set to `true`, the subscription automatically
renews at the end of the current term.
latest_version:
type: boolean
description: If true, this is the latest version of the subscription
initial_term:
allOf:
- $ref: '#/components/schemas/term'
description: Initial term information for the subscription.
current_term:
allOf:
- $ref: '#/components/schemas/term'
description: Current term information for the subscription
renewal_term:
allOf:
- $ref: '#/components/schemas/term'
description: Renewal term information for the subscription.
start_date:
type: string
format: date
description: Date when the subscription starts.
example: '2020-01-01'
end_date:
type: string
format: date
description: Date when the subscription ends.
example: '2023-01-01'
description:
type: string
description: >-
Description of the subscription. Often useful for displaying to
users.
contract_effective:
type: string
format: date
description: Date when the subscriber contract is effective.
example: '2023-01-01'
service_activation:
type: string
format: date
description: Date when the subscribed-to service is activated.
example: '2023-01-01'
customer_acceptance:
type: string
format: date
description: >-
Date when all the services or products in the subscription are
accepted by the subscriber.
example: '2023-01-01'
invoice_separately:
type: boolean
description: >-
If true, the subscription is billed separately from other
subscriptions. If false, the subscription is included with other
subscriptions in the account invoice. The default is false.
order_number:
type: string
description: The order number of the order created by Zuora.
subscription_plans:
allOf:
- $ref: '#/components/schemas/subscriptionPlanListResponse'
readOnly: true
description: List of subscription plans.
invoice_items:
allOf:
- $ref: '#/components/schemas/invoiceItemListResponse'
readOnly: true
description: List of invoice items.
prepaid_balance:
type: array
items:
$ref: '#/components/schemas/prepaidBalance'
readOnly: true
deprecated: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription. **Deprecated, please
use `prepaid_balances` instead.**
prepaid_balances:
type: array
items:
$ref: '#/components/schemas/prepaidBalances'
readOnly: true
description: >-
Total prepaid units available during a subscription. It is an
aggregate of all funds under a subscription.
contracted_mrr:
type: string
description: Monthly recurring revenue of the subscription.
currency:
type: string
description: >-
3-letter ISO 4217 currency code. This field is available only if you
have the [Multiple
Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies)
feature enabled.
cancel_reason:
type: string
description: The reason for cancelling the subscription.
last_booking_date:
type: string
format: date
description: >-
The last booking date of the subscription object. You can override
the date value when creating a subscription through the "Subscribe
and Amend" API. The default value `today` is set per the user's
timezone. The value of this field is as follows: <ul> <li>For
a new subscription created by the [Subscribe and
Amend](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate)
APIs, this field has the value of the subscription creation date.
</li> <li>For a subscription changed by an amendment, this field
has the value of the amendment booking date.</li> <li>For a
subscription created or changed by an order, this field has the
value of the order date.</li> </ul>
example: '2023-01-01'
bill_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the bill-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
payment_terms:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: The name of payment term associated with the invoice.
bill_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The billing address for the customer.
billing_document_settings:
allOf:
- $ref: '#/components/schemas/flexibleBillingDocumentSettings'
description: The billing document settings for the customer.
sold_to_id:
type: string
nullable: true
x-extra-field-annotation: '@JsonAdapter(NullableFieldAdapter.class)'
description: ID of the sold-to contact.
example: 2c92c0f86a8dd422016a9e7a70116b0d
sold_to:
allOf:
- $ref: '#/components/schemas/contact'
readOnly: true
description: The selling address for the customer.
actions:
type: array
items:
$ref: '#/components/schemas/orderAction'
ar_transactions:
allOf:
- $ref: '#/components/schemas/arTransactionsOrders'
orderSubscriptionPreviewResponse:
type: object
title: OrderSubscriptionPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
actions:
type: array
items:
allOf:
- $ref: '#/components/schemas/subscriptionPreviewActionsResponse'
orderPreviewResponse:
type: object
title: OrderPreviewResponse
description: ''
nullable: false
additionalProperties: false
properties:
subscriptions:
type: array
items:
allOf:
- $ref: '#/components/schemas/orderSubscriptionPreviewResponse'
billing_documents:
type: array
items:
allOf:
- $ref: >-
#/components/schemas/subscriptionPreviewBillingDocumentsResponse
line_items:
type: array
items:
allOf:
- $ref: '#/components/schemas/lineItemsPreviewResponse'
description: The order line items on this order.
subscriptionPlan:
type: object
title: SubscriptionPlan
description: Subscription plan information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
description: The subscription to which this subscription plan belongs.
subscription_id:
type: string
description: Identifier of the subscription this subscription plan belongs to.
product_id:
type: string
description: Identifier of the product associated with this subscription plan.
plan_id:
type: string
description: Identifier of the plan associated with this subscription plan.
plan:
allOf:
- $ref: '#/components/schemas/plan'
description: The plan object associated with this subscription plan.
product:
allOf:
- $ref: '#/components/schemas/product'
description: The product associated with the subscription plan.
name:
type: string
description: The name of the subscription plan.
subscription_items:
allOf:
- $ref: '#/components/schemas/subscriptionItemListResponse'
readOnly: true
description: List of subscription items.
subscription_plan_number:
type: string
description: Human-readable number of the subscription plan.
subscriptionPlanListResponse:
type: object
title: SubscriptionPlanListResponse
description: A list of subscription plans
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/subscriptionPlan'
subscriptionItemPrepaymentField:
type: object
title: SubscriptionItemPrepaymentField
description: The prepayment information.
additionalProperties: false
properties:
quantity:
type: number
description: The number of units included in a prepayment charge.
validity_period:
type: string
enum:
- subscription_term
- annual
- semi_annual
- quarter
- month
description: >-
The period in which the prepayment units are valid to use as defined
in a prepayment charge.
subscriptionItemDrawdownField:
type: object
title: SubscriptionItemDrawdownField
description: The drawdown information.
additionalProperties: false
properties:
conversion_rate:
type: number
description: >-
The conversion rate between usage unit of measure (UOM) and drawdown
unit of measure for a drawdown charge. **Note**: <ul>
<li>Must be a positive number (>0).</li> <li>Must be `1` when
usage UOM and drawdown UOM are the same.</li> <li>If both
`conversion_rate` and `unit_of_measure` for the drawdown are empty,
the system will set default values respectively: <ul> <li>
`conversion_rate`: 1 </li> <li> `unit_of_measure`: Same as the
usage UOM of this drawdown charge. </li></ul></li></ul> The
`conversion_rate` and `unit_of_measure` fields need to have values
or be empty at the same time.
subscriptionItem:
type: object
title: SubscriptionItem
description: Subscription item information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription_item_number:
type: string
description: >-
Human-readable identifier of the subscription item. It can be
user-supplied.
name:
type: string
description: The name of the subscription item.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
product_id:
type: string
description: >-
Identifier of the product with which this subscription is
associated.
charged_through_date:
type: string
format: date
description: >-
The date through which a customer has been billed for the
subscription item.
recurring:
type: object
title: Recurring
description: The recurring components of a price such as interval and usage.
additionalProperties: false
properties:
recurring_on:
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
'on':
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
deprecated: true
x-replaced-by: recurring_on
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
usage:
type: boolean
description: Indicates that this is a usage price.
interval:
type: string
enum:
- month
- year
- week
- term
- day
description: >-
Specifies the billing frequency. One of `week`, `month` or
`year`.
interval_count:
type: integer
description: >-
The number of intervals (specified in the interval attribute)
between subscription billings. For example, interval=month and
intervalCount=3 bills every 3 months.
alignment_behavior:
type: string
enum:
- subscription_start
- term_start
- term_end
- none
description: >-
Specifies how to align billing for recurring (subscription)
products that start on different days.
timing:
type: string
enum:
- in_advance
- in_arrears
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based
prices.
formula:
type: string
readOnly: true
description: >-
You can choose to bill in_advance or in_arrears for recurring
prices. The field is not used with one-time or usage-based
prices.
duration_interval:
type: string
enum:
- day
- week
- month
- year
- subscription_term
- billing_period
description: >-
Specifies the duration frequency. One of day, week, month or
year.
duration_interval_count:
type: integer
description: >-
Specifies how long a customer shall be charged if this is less
than the duration of the subscription
rating_group:
type: string
enum:
- billing_period
- usage_start_date
- usage_record
- usage_upload
- custom_group
description: >-
A rating group based on which usage records are rated. Only
applicable to usage prices.
active:
type: boolean
description: >-
Indicates whether the price is active and can be used for new
purchases.
state:
type: string
enum:
- inactive
- active
- expired
description: >-
Based on the current date to populate a state field with the
enumeration: [inactive, active, expired] where inactive would
represent charge segments with a start_date in the future and
expired charge segments with an end_date in the past.
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
description: Specifies the kind of tiering.
tiers:
type: array
items:
$ref: '#/components/schemas/itemTier'
tax_code:
type: string
description: >-
A tax code identifier. If the `tax_code` of a price is not provided
when you create or override a price, Zuora will treat the charged
amount as non-taxable. If this code is provide, Zuora considers that
this price is taxable and the charged amount will be handled
accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for per-unit
prices.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
amount:
type: number
description: >-
The amount of the price. Specify this field if you want to override
the original price with a flat-fee price
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the original price with a per-unit price.
discount_amount:
type: number
description: >-
Discount amount. Specify this field if you offer an amount-based
discount.
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one_time, recurring and plan.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: one of
account, subscription or plan.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
description: >-
Specifies the base interval of the price the subscriber is
subscribed to. If not provided, this field defaults to
`billing_period`.
overage:
type: object
title: Overage
description: An object defining how overage charges are calculated.
additionalProperties: false
properties:
interval_count:
type: integer
description: >-
Specifies the number of intervals used to calculate smoothed
overage charges.
type:
type: string
enum:
- rolling_window
- rollover
description: 'Represents the overage type: one of rolling_window or rollover.'
included_units:
type: number
description: >-
Specifies the included units to which overage charges do not
apply.
credit_unused_units:
type: boolean
description: Specifies whether or not to credit unused units.
apply_at_end_of_smoothing_period:
type: boolean
description: >-
Indicates if the overage price is calculated at the end of the
smoothing period.
charge_model:
type: string
description: >-
Charge model of the price. See [Charge
models](https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/B_Charge_Models)
for more information.
charge_type:
type: string
description: >-
Type of the charge. It can be one of the following types: one-time,
recurring, or usage.
price_id:
type: string
description: Identifier of the price.
price:
type: object
title: Price
description: Price information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601
UTC format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful
for storing additional information about the object in a
structured format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
name:
type: string
description: The name of the price.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
recognized_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
deferred_revenue_accounting_code:
type: string
maxLength: 100
description: An active accounting code in your Zuora chart of accounts.
recurring:
type: object
title: Recurring
description: The recurring components of a price such as interval and usage.
additionalProperties: false
properties:
recurring_on:
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
'on':
type: string
enum:
- _1
- _2
- _3
- _4
- _5
- _6
- _7
- _8
- _9
- _10
- _11
- _12
- _13
- _14
- _15
- _16
- _17
- _18
- _19
- _20
- _21
- _22
- _23
- _24
- _25
- _26
- _27
- _28
- _29
- _30
- _31
- subscription_item_start_day
- account_cycle_date
- subscription_start_day
- term_end_day
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
deprecated: true
x-replaced-by: recurring_on
description: >-
Specifies on which day or the month or day of the week a
customer shall be billed.
usage:
type: boolean
description: Indicates that this is a usage price.
interval:
type: string
enum:
- month
- year
- week
- term
- day
description: >-
Specifies the billing frequency. One of `week`, `month` or
`year`.
interval_count:
type: integer
description: >-
The number of intervals (specified in the interval
attribute) between subscription billings. For example,
interval=month and intervalCount=3 bills every 3 months.
alignment_behavior:
type: string
enum:
- subscription_start
- term_start
- term_end
- none
description: >-
Specifies how to align billing for recurring (subscription)
products that start on different days.
timing:
type: string
enum:
- in_advance
- in_arrears
description: >-
You can choose to bill in_advance or in_arrears for
recurring prices. The field is not used with one-time or
usage-based prices.
formula:
type: string
readOnly: true
description: >-
You can choose to bill in_advance or in_arrears for
recurring prices. The field is not used with one-time or
usage-based prices.
duration_interval:
type: string
enum:
- day
- week
- month
- year
- subscription_term
- billing_period
description: >-
Specifies the duration frequency. One of day, week, month or
year.
duration_interval_count:
type: integer
description: >-
Specifies how long a customer shall be charged if this is
less than the duration of the subscription
rating_group:
type: string
enum:
- billing_period
- usage_start_date
- usage_record
- usage_upload
- custom_group
description: >-
A rating group based on which usage records are rated. Only
applicable to usage prices.
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
deprecated: true
description: Specifies the mode for tiered prices.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one_time, recurring and plan.
tiers:
type: array
items:
$ref: '#/components/schemas/tier'
description: >-
Price information for different tiers. When creating or updating
tiered prices, you must specify this field and the `tiers_mode`
field.
tax_code:
type: string
description: >-
A tax code identifier. If a `tax_code` of a price is not
provided when you create or update a price, Zuora will treat the
charged amount as non-taxable. If this code is provide, Zuora
considers that this price is taxable and the charged amount will
be handled accordingly.
tax_inclusive:
type: boolean
description: >-
If this field is set to `true`, it indicates that amounts are
inclusive of tax.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for
per-unit prices.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
min_quantity:
type: number
description: >-
The minimum quantity for a price. Specify this field and the
`max_quantity` field to create a range of quantities allowed in
a price.
max_quantity:
type: number
description: >-
The maximum quantity for a price. Specify this field and the
`min_quantity` field to create a range of quantities allowed in
a price.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: account,
subscription, or plan.
revenue_recognition_rule:
type: string
enum:
- on_invoice
- daily_over_time
description: >-
Determines when to recognize the revenue for this charge. You
can choose to recognize upon invoicing or daily over time.
stacked_discount:
type: boolean
description: >-
This field is only applicable for the Percentage Discount price.
This field indicates whether the discount is to be calculated as
stacked discount. Possible values are as follows:
<ul> <li>`true`: This is a stacked discount, which should
be calculated by stacking with other discounts.</li> <li>
`false`: This is not a stacked discount, which should be
calculated in sequence with other discounts.</li></ul> For more
information, see <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models'
target='_blank'>Stacked discounts</a>
amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
unit_amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
discount_amounts:
type: object
additionalProperties:
type: number
example:
USD: 10
GBP: 15
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a
percentage-based discount.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
description: >-
Specifies the base interval of a price. If not provided, this
field defaults to `billing_period`.
overage:
allOf:
- $ref: '#/components/schemas/overage'
deprecated: true
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
accounting_code:
type: string
description: >-
An active accounting code defined in **Finance Settings >
Configure Accounting Codes** in your Zuora tenant.
prepayment:
type: object
title: Prepayment
description: ''
nullable: false
additionalProperties: false
properties:
credit_option:
type: string
enum:
- time_based
- consumption_based
- full_credit
description: >-
The way to calculate credit. See <a
href='https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_with_Drawdown/A_Create_prepayment_charge#Credit_Option'
target='_blank'>Credit Option</a> for more information.
quantity:
type: number
description: The number of units included in a prepayment charge.
total_quantity:
type: number
description: >-
The total amount of units that end customers can use during
a validity period when they subscribe to a prepayment
charge.
unit_of_measure:
type: string
description: >-
A configured unit of measure. This field is required for
per-unit prices.
validity_period:
type: string
enum:
- subscription_term
- annual
- semi_annual
- quarter
- month
description: >-
The period in which the prepayment units are valid to use as
defined in a prepayment charge.
drawdown:
type: object
title: Drawdown
description: ''
nullable: false
additionalProperties: false
properties:
conversion_rate:
type: number
description: >-
The conversion rate between usage unit of measure (UOM) and
drawdown unit of measure for a drawdown charge.
**Note**: <ul> <li>Must be a positive number
(>0).</li> <li>Must be `1` when usage UOM and drawdown
UOM are the same.</li> <li>If both `conversion_rate` and
`unit_of_measure` for the drawdown are empty, the system
will set default values respectively: <ul> <li>
`conversion_rate`: 1 </li> <li> `unit_of_measure`: Same
as the usage UOM of this drawdown charge.
</li></ul></li></ul> The `conversion_rate` and
`unit_of_measure` fields need to have values or be empty at
the same time.
unit_of_measure:
type: string
description: Unit of measurement for a drawdown charge.
taxable:
type: boolean
price_change_percentage:
type: number
description: >-
The percentage to increase or decrease the price of a termed
subscription's renewal.
price_change_option:
type: string
enum:
- latest_catalog_pricing
- percentage
- none
default: none
description: >-
Applies an automatic price change when a termed subscription is
renewed.
price_increase_option:
type: boolean
description: >-
Indicates whether to apply an automatic price change when a
termed subscription is renewed.
plan_id:
type: string
description: Specify the ID of a plan to which this price is associated.
plan_number:
type: string
description: >-
Specify the number of a plan to which this price is associated.
This field is required if plan_id is not supplied
custom_field_per_unit_rate:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a per unit
rate under the `Pre-Rated Per Unit` charge model
custom_field_total_amount:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a total amount
under the `Pre-Rated` charge model
active:
type: boolean
deprecated: true
description: Whether the price can be used for new purchases.
charge_type:
type: string
description: The type of charge. Can be `one_time`,`recurring`, or `usage`.
charge_model:
type: string
description: >-
The charge model of the price, which determines how users are
charged. Common charge models include flat fee, per-unit,
volume, and tiered prices.
subscription_plan_id:
type: string
description: >-
Identifier of the subscription plan this subscription item belongs
to.
subscription_plan:
type: object
title: SubscriptionPlan
description: Subscription plan information.
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601
UTC format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful
for storing additional information about the object in a
structured format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
description: The subscription to which this subscription plan belongs.
subscription_id:
type: string
description: >-
Identifier of the subscription this subscription plan belongs
to.
product_id:
type: string
description: >-
Identifier of the product associated with this subscription
plan.
plan_id:
type: string
description: Identifier of the plan associated with this subscription plan.
plan:
allOf:
- $ref: '#/components/schemas/plan'
description: The plan object associated with this subscription plan.
product:
allOf:
- $ref: '#/components/schemas/product'
description: The product associated with the subscription plan.
name:
type: string
description: The name of the subscription plan.
subscription_items:
allOf:
- $ref: '#/components/schemas/subscriptionItemListResponse'
readOnly: true
description: List of subscription items.
subscription_plan_number:
type: string
description: Human-readable number of the subscription plan.
start_date:
type: string
format: date
readOnly: true
description: The date when the subscription item starts.
end_date:
type: string
format: date
readOnly: true
description: The date when the subscription item ends.
processed_through_date:
type: string
format: date
readOnly: true
description: >-
The date until when charges are processed. When billing takes place
in arrears, such as usage-based prices, this field value is the the
same as the `ChargedThroughDate` value. This date is the earliest
date when a charge can be amended.
subscriptionItemListResponse:
type: object
title: SubscriptionItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/subscriptionItem'
billingDocumentItemListResponse:
type: object
title: BillingDocumentItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/billingDocumentItem'
billingDocumentItem:
type: object
title: BillingDocumentItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
amount:
type: number
description: The total amount of this billing document item.
subtotal:
type: number
description: The total amount of this billing document item exclusive of tax.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: >-
The accounting code for the deferred revenue, such as Monthly
Recurring Liability.
on_account_account:
type: string
description: >-
The accounting code that maps to an on account in your accounting
system.
recognized_revenue_account:
type: string
description: >-
The accounting code for the recognized revenue, such as Monthly
Recurring Charges or Overage Charges.
billing_document:
allOf:
- $ref: '#/components/schemas/billingDocument'
description: The related billing document.
billing_document_id:
type: string
description: The related billing document id.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
description: >-
The end date of the service period associated with this billing
document item. If the associated charge is a one-time fee, then this
date is the date of that charge.
accounts_receivable_account:
type: string
description: An active account in your Zuora Chart of Accounts.
discount_item:
type: boolean
description: If true, indicates that the item is a discount item.
applied_to_item_id:
type: string
description: >-
Identifier of an invoice item or a debit memo item that this
discount item or credit memo item is applied to.
service_start:
type: string
description: >-
The start date of the service period associated with this billing
document item. If the associated charge is a one-time fee, then this
date is the date of that charge.
accounting_code:
type: string
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
product_name:
type: string
description: The name of the product associated with this item.
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the billing
document item.
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
description: >-
The expandable subscription associated with the billing document
item.
tax_inclusive:
type: boolean
description: >-
This specifies if the billing document item amount is inclusive or
exclusive of tax.
remaining_balance:
type: number
description: The remaining balance of this billing document item.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
unit_amount:
type: number
description: >-
Unit amount (in the currency specified) of the billing document
item.
booking_reference:
type: string
description: The booking reference for this billing document item.
price_description:
type: string
description: >-
The description of the price this billing document item is
associated with.
name:
type: string
description: >-
Name of the billing document item displayed to customers on the
billing document.
price_id:
type: string
description: >-
The identifier of the price this billing document item is associated
with.
purchase_order_number:
type: string
description: >-
The purchase order number associated with this billing document
item.
tax:
type: number
description: The amount of tax applied to the billing document item.
tax_code:
type: string
description: The designated tax code.
subscription_item_id:
type: string
description: >-
The identifier the subscription item associated with this billing
document item.
subscription_item:
allOf:
- $ref: '#/components/schemas/subscriptionItem'
description: >-
The expandable subscription item associated with this billing
document item.
invoice_item_id:
type: string
description: >-
The identifier of the invoice item associated with this billing
document item.
document_item_date:
type: string
format: date-time
description: The date when the billing document item takes effect.
example: '2022-01-01T07:08:12-07:00'
taxation_items:
allOf:
- $ref: '#/components/schemas/taxationItemListResponse'
description: List of taxation items.
type:
type: string
enum:
- credit_memo
- debit_memo
- invoice
description: >-
The type of billing document, one of credit_memo, debit_memo or
invoice.
billingDocumentItemCreateRequest:
type: object
title: BillingDocumentItemCreateRequest
description: ''
additionalProperties: false
properties:
amount:
type: number
description: >-
Amount (in the currency specified) of the invoice item. This should
always be equal to unit_amount * quantity.
description:
type: string
description: >-
An arbitrary string associated with the object. Often useful for
displaying to users.
deferred_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
on_account_account:
type: string
description: An active account in your Zuora Chart of Accounts.
recognized_revenue_account:
type: string
description: An active account in your Zuora Chart of Accounts.
revenue_recognition_rule_name:
type: string
description: >-
The name of the revenue recognition rule governing the revenue
schedule.
quantity:
type: number
description: The number of units of this item.
service_end:
type: string
format: date
description: >-
The end date of the service period associated with this billing
document item. If the price for the associated subscription item is
a one-time fee, then this date is the date of that subscription
item.
example: '2022-01-01'
service_start:
type: string
format: date
description: >-
The start date of the service period associated with this billing
document item. If the price for the associated subscription item is
a one-time fee, then this date is the date of that subscription
item.
example: '2022-01-01'
sku:
type: string
description: >-
The unique SKU (stock keeping unit) of the product associated with
this item.
tax_inclusive:
type: boolean
description: >-
Indicates whether the billing document item amount is inclusive or
exclusive of tax.
unit_of_measure:
type: string
description: Specifies the units used to measure usage.
taxation_items:
type: array
items:
$ref: '#/components/schemas/taxationItemCreateRequest'
description: List of taxation items.
unit_amount:
type: number
description: >-
Unit amount (in the currency specified) of the billing document
item.
booking_reference:
type: string
description: The booking reference for this billing document item.
price_id:
type: string
description: >-
The identifier of the price this billing document item is associated
with.
purchase_order_number:
type: string
description: >-
The purchase order number associated with this billing document
item.
tax_code:
type: string
description: The designated tax code.
document_item_date:
type: string
format: date-time
description: >-
The date when the billing document item takes effect. This field is
applicable only if the `type` field is set to `invoice`.
example: '2022-01-01T07:08:12-07:00'
name:
type: string
description: >-
Name of the billing document item displayed to customers on the
billing document.
invoice_item_id:
type: string
description: >-
The identifier of the invoice item associated with this billing
document item.
accounting_code:
type: string
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- service_start
subscriptionItemCreateRequest:
type: object
title: SubscriptionItemCreateRequest
description: ''
additionalProperties: false
properties:
price_id:
type: string
description: Identifier of the price.
subscription_item_number:
type: string
description: >-
Human-readable identifier of the subscription item. It can be
user-supplied.
description:
type: string
maxLength: 500
description: Description of the price. Often useful for displaying to users.
recurring:
$ref: '#/components/schemas/recurring'
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
start_date:
type: string
format: date
description: The date when the subscription item starts
end_date:
type: string
format: date
description: The date when the subscription item ends or ended.
tiers_mode:
type: string
enum:
- graduated
- volume
- high_watermark_volume
- high_watermark_graduated
- graduated_with_overage
description: Specifies the mode of tiering.
tiers:
type: array
items:
$ref: '#/components/schemas/itemTier'
description: Information of all tiers if the price is a tiered price.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
amount:
type: number
description: >-
The amount of the price. Specify this field if you want to override
the original price with a flat-fee price
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the original price with a per-unit price.
discount_amount:
type: number
description: >-
Discount amount. Specify this field if you offer an amount-based
discount.
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you offer a percentage-based
discount.
price_base_interval:
type: string
enum:
- month
- billing_period
- week
description: >-
Specifies the base interval of the price the subscriber is
subscribed to. If not provided, this field defaults to
`billing_period`.
overage:
$ref: '#/components/schemas/overage'
unique_token:
type: string
maxLength: 50
description: >-
Unique identifier for the price. This identifier enables you to
refer to the price before the price has an internal identifier in
Zuora.
custom_fields:
$ref: '#/components/schemas/customFields'
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one-time, recurring, and usage.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: >-
Specifies at what level a discount should be applied: one of
account, subscription or plan.
custom_field_per_unit_rate:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a per unit rate
under the `Pre-Rated Per Unit` charge model
custom_field_total_amount:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a total amount
under the `Pre-Rated` charge model
price_change_percentage:
type: number
description: >-
The percentage to increase or decrease the price of a termed
subscription's renewal.
price_change_option:
type: string
enum:
- latest_catalog_pricing
- percentage
- none
default: none
description: >-
Applies an automatic price change when a termed subscription is
renewed.
prepayment:
$ref: '#/components/schemas/subscriptionItemPrepaymentField'
drawdown:
$ref: '#/components/schemas/subscriptionItemDrawdownField'
required:
- price_id
subscriptionItemPatchRequest:
type: object
title: SubscriptionItemPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Identifier of the subscription item.
recurring:
$ref: '#/components/schemas/recurring'
subscription_item_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
start_date:
type: string
format: date
description: The date when the subscription item starts
end_date:
type: string
format: date
description: The date when the subscription item ends or ended.
apply_discount_to:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Any combination of one-time, recurring, or usage prices.
discount_level:
type: string
enum:
- account
- subscription
- plan
description: Specifies at what level a discount should be applied.
start_event:
type: string
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
description: Specifies when to start billing your customer.
discount_percent:
type: number
description: >-
Discount percent. Specify this field if you want to override with a
discount-based discount price.
quantity:
type: number
description: Quantity of the product to which your customers subscribe.
amount:
type: number
description: >-
The amount of the price. Specify this field if you want to override
the original price with a flat-fee price
unit_amount:
type: number
description: >-
The unit amount of the price. Specify this field if you want to
override the orignial price with a per-unit price.
tiers:
type: array
items:
$ref: '#/components/schemas/itemTier'
description: >-
Information of all tiers if you want to override the original price
with a tiered price.
overage:
$ref: '#/components/schemas/overage'
unique_token:
type: string
description: >-
Unique identifier for the price. This identifier enables you to
refer to the price before the price has an internal identifier in
Zuora.
prepayment:
$ref: '#/components/schemas/subscriptionItemPrepaymentField'
custom_field_per_unit_rate:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a per unit rate
under the `Pre-Rated Per Unit` charge model
custom_field_total_amount:
type: string
writeOnly: true
description: >-
Name of the custom field that will be used to set a total amount
under the `Pre-Rated` charge model
billRun:
type: object
title: BillRun
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier for this object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: Identifier of the customer account to bill.
email:
type: boolean
description: >-
If set to `true`, invoices will be automatically emailed to
customers.
post:
type: boolean
description: >-
Indicates whether to automatically post a billing document after it
is created.
renew:
type: boolean
description: If set to `true`, subscriptions will be automatically renewed.
day_of_month:
type: string
description: The day of the month to bill multiple customer accounts.
bill_run_number:
type: string
description: Human-readable identifier for this object.
bill_run_time:
type: string
format: date-time
description: The date and time on which this bill run starts.
invoice_date:
type: string
format: date
description: The date displayed on the invoice.
example: '2022-01-01'
target_date:
type: string
format: date
description: >-
All unbilled items on or before this date are included in this bill
run.
example: '2023-01-01'
state:
type: string
enum:
- processed
- pending
- completed
- canceled
- posted
- failed
description: Status of the bill run.
batches:
type: string
description: >-
Identifier of the customer account batch to be included in this bill
run.
charges_excluded:
type: string
description: Type of the charge to be excluded from the bill run.
email_zero_amount_invoices:
type: boolean
description: >-
If set to `false`, invoices for zero amounts will not be emailed to
customers.
invoices_sent:
type: boolean
description: >-
Indicates whether the invoices have been automatically sent to
customers.
last_invoice_sent_time:
type: string
format: date
description: The date when the last invoice was sent.
example: '2023-01-01'
accounts_processed:
type: integer
description: Number of accounts billed from this bill run.
invoices_generated:
type: integer
description: Number of invoices generated from this bill run.
credit_memos_generated:
type: integer
description: Number of credit memos generated from this bill run.
name:
type: string
description: The name of the bill run.
BillRunCreateRequest:
type: object
title: BillRunCreateRequest
description: ''
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
$ref: '#/components/schemas/customFields'
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: >-
Identifier of the customer account to bill. Specify this field or
`account_number` if you want to create a bill run for a single
customer.
account_number:
type: string
description: >-
Human-readable identifier of the account to bill. Specify this field
or `account_id` if you want to create a bill run for a single
customer.
email:
type: boolean
description: >-
If set to `true`, invoices will be automatically emailed to
customers.
post:
type: boolean
description: >-
Indicates whether to automatically post a billing document after it
is created.
renew:
type: boolean
description: If set to `true`, subscriptions will be automatically renewed.
day_of_month:
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '10'
- '11'
- '12'
- '13'
- '14'
- '15'
- '16'
- '17'
- '18'
- '19'
- '20'
- '21'
- '22'
- '23'
- '24'
- '25'
- '26'
- '27'
- '28'
- '29'
- '30'
- '31'
- AllBillCycleDays
- AsRunDay
description: >-
The day of the month on which the multiple customer accounts are
billed.
batches:
type: array
items:
type: string
description: >-
Identifier of the customer account batch to be included in this bill
run.
invoice_date:
type: string
format: date
description: The date displayed on the invoice.
example: '2022-01-01'
target_date:
type: string
format: date
description: >-
All unbilled items on or before this date are included in this bill
run.
example: '2023-01-01'
email_zero_amount_invoices:
type: boolean
default: true
description: >-
If it is set to `false`, invoices for zero amounts will not be
emailed to customers.
charges_excluded:
type: array
items:
type: string
description: Type of the charge to be excluded from the bill run.
name:
type: string
description: The name of the bill run.
type:
type: string
enum:
- regular
- catch_up
description: >-
The type of the bill run. This field is only available if you have
the <a
href=â€https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Automate_billing_document_generation/Bill_runs/Z_Catch-Up_Bill_Runâ€
target=â€_blankâ€>Catch-Up Bill Run</a> feature enabled in your
tenant.
subscription_ids:
type: array
items:
type: string
description: >-
The target subscriptions for this bill run. Note that all these
subscriptions must belong to the same account.
required:
- invoice_date
- target_date
BillRunPostRequest:
type: object
title: BillRunPostRequest
description: ''
additionalProperties: false
properties:
invoice_date:
type: string
format: date
description: The date printed on the invoice.
example: '2022-01-01'
required:
- invoice_date
BillRunListResponse:
type: object
title: BillRunListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/billRun'
billRunPreview:
type: object
title: BillRunPreview
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
assume_renewal:
type: string
enum:
- all
- auto_renew_only
- none
description: >-
Indicates whether to generate a preview of future invoice items and
credit memo items with the assumption that the subscriptions are
renewed. **all**: The assumption is applied to all the
subscriptions. Zuora generates preview invoice item data and credit
memo item data from the first day of the customer's next billing
period to the target date. **auto_renew_only**: The assumption is
applied to the subscriptions that have auto_renew enabled. Zuora
generates preview invoice item data and credit memo item data from
the first day of the customer's next billing period to the target
date.
batches:
type: array
items:
type: string
description: >-
Identifiers of the customer account batches to be included in this
bill run preview.
charges_excluded:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Charge type or types to be excluded from this bill run preview.
include_draft_items:
type: boolean
description: If true, draft items will be included in this bill run preview.
include_evergreen_subscriptions:
type: boolean
description: >-
If true, evergreen subscriptions will be included in this bill run
preview.
target_date:
type: string
format: date
description: >-
All unbilled items on or before this date are included in this bill
run.
state_transitions:
type: object
title: BillRunPreviewStateTransitions
description: The timestamps at which the object's state was updated.
additionalProperties: false
properties:
complete_time:
type: string
format: date-time
description: The time when the bill run preview completed.
processing_start_time:
type: string
format: date-time
description: The time when the bill run preview started.
file:
type: object
title: BillRunPreviewFile
description: File containing the results of the bill run preview.
additionalProperties: false
properties:
url:
type: string
description: >-
The URL from which a zipped CSV file may be downloaded. This
file contains the preview invoice item data and credit memo item
data for the specified customer accounts.
billing_preview_run_number:
type: string
description: Human-readable identifier for this object.
state:
type: string
enum:
- pending
- processing
- completed
- failed
- canceled
description: The state of the bill run preview.
number_of_accounts_succeeded:
type: number
description: >-
The number of the customer accounts whose bill run preview job
succeeded.
number_of_accounts:
type: number
description: >-
The number of the customer accounts included in the bill run preview
job.
billRunPreviewCreateRequest:
type: object
title: BillRunPreviewCreateRequest
description: ''
additionalProperties: false
properties:
assume_renewal:
type: string
enum:
- all
- auto_renew_only
- none
description: >-
Indicates whether to generate a preview of future invoice items and
credit memo items with the assumption that the subscriptions are
renewed. **all**: The assumption is applied to all the
subscriptions. Zuora generates preview invoice item data and credit
memo item data from the first day of the customer's next billing
period to the target date. **auto_renew_only**: The assumption is
applied to the subscriptions that have auto_renew enabled. Zuora
generates preview invoice item data and credit memo item data from
the first day of the customer's next billing period to the target
date.
batches:
type: array
items:
type: string
description: >-
Identifiers of the customer account batches to be included in this
bill run preview.
charges_excluded:
type: array
items:
type: string
enum:
- one_time
- recurring
- usage
description: Charge type or types to be excluded from this bill run preview.
include_draft_items:
type: boolean
description: If true, draft items will be included in this bill run preview.
include_evergreen_subscriptions:
type: boolean
description: >-
If true, evergreen subscriptions will be included in this bill run
preview.
target_date:
type: string
format: date
description: >-
All unbilled items on or before this date are included in this bill
run.
required:
- target_date
subscriptionPlanPatchRequest:
type: object
title: SubscriptionPlanPatchRequest
description: Subscription Plan information.
additionalProperties: false
properties:
custom_fields:
$ref: '#/components/schemas/customFields'
subscription_plan_id:
type: string
description: Identifier of the subscription plan.
unique_token:
type: string
description: >-
Unique identifier for the subscription plan. This identifier enables
you to refer to the subscription plan before the subscription plan
has an internal identifier in Zuora.
subscription_items:
type: array
items:
allOf:
- $ref: '#/components/schemas/subscriptionItemPatchRequest'
description: Subscription item information.
subscriptionPlanCreateRequest:
type: object
title: SubscriptionPlanCreateRequest
description: Subscription plan information.
additionalProperties: false
properties:
plan_id:
type: string
description: Identifier of the plan associated with this subscription plan.
plan_number:
type: string
description: >-
Human-readable identifier of the plan associated with this
subscription plan.
prices:
type: array
items:
allOf:
- $ref: '#/components/schemas/subscriptionItemCreateRequest'
description: Price information within the subscription plan.
unique_token:
type: string
description: >-
Unique identifier for the subscription plan. This identifier enables
you to refer to the subscription plan before the subscription plan
has an internal identifier in Zuora.
custom_fields:
$ref: '#/components/schemas/customFields'
usageCreateRequest:
type: object
title: UsageCreateRequest
description: ''
additionalProperties: false
properties:
account_number:
type: string
description: >-
Human-readable identifier of the account. It can be user-supplied.
Either `account_number` or `account_id` is required.
example: A-100001
account_id:
type: string
description: >-
Identifier of the account associated with this subscription. Either
`account_id` or `account_number` is required.
subscription_item_id:
type: string
description: Identifier of the subscription item.
subscription_item_number:
type: string
description: Human-readable identifier of the subscription item.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
end_time:
type: string
format: date-time
description: The end time for which usage is recorded.
quantity:
type: number
description: The number of units of this item.
start_time:
type: string
format: date-time
description: The start time for which usage is recorded.
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the billing
document item.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
unit_of_measure:
type: string
description: >-
Specifies the units to measure usage. Units of measure are
configured in Zuora Central. Your values depend on your
configuration in Billing Settings.
custom_fields:
$ref: '#/components/schemas/customFields'
required:
- start_time
- quantity
- unit_of_measure
usage:
type: object
title: Usage
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_number:
type: string
description: >-
Human-readable identifier of the account. It can be user-supplied.
Either `account_number` or `account_id` is required.
example: A-100001
account_id:
type: string
description: >-
Identifier of the account associated with this subscription. Either
`account_id` or `account_number` is required.
subscription_item_id:
type: string
description: Identifier of the subscription item.
subscription_item_number:
type: string
description: Human-readable identifier of the subscription item.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
end_time:
type: string
format: date-time
description: The end time for which usage is recorded.
quantity:
type: number
description: The number of units of this item.
start_time:
type: string
format: date-time
description: The start time for which usage is recorded.
subscription_id:
type: string
description: >-
The identifier of the subscription associated with the billing
document item.
subscription_number:
type: string
description: >-
Human-readable identifier of the subscription. It can be
user-supplied.
unit_of_measure:
type: string
description: >-
Specifies the units to measure usage. Units of measure are
configured in Zuora Central. Your values depend on your
configuration in Billing Settings.
state:
type: string
enum:
- pending
- processed
account:
allOf:
- $ref: '#/components/schemas/account'
description: The account that owns the usages. EXPANDABLE
subscription_item:
allOf:
- $ref: '#/components/schemas/subscriptionItem'
description: The related subscription item.
subscription:
allOf:
- $ref: '#/components/schemas/subscription'
description: The subscription to which this subscription plan belongs.
usagePatchRequest:
type: object
title: UsagePatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
end_time:
type: string
format: date-time
description: The end time for which usage is recorded.
quantity:
type: number
description: The number of units of this item.
start_time:
type: string
format: date-time
description: The start time for which usage is recorded.
unit_of_measure:
type: string
description: >-
Specifies the units to measure usage. Units of measure are
configured in Zuora Central. Your values depend on your
configuration in Billing Settings.
custom_fields:
$ref: '#/components/schemas/customFields'
listUsageResponse:
type: object
title: ListUsageResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/usage'
workflowRun:
type: object
title: WorkflowRun
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: integer
description: The unique ID of an active version.
type:
type: string
enum:
- setup
- instance
description: >-
The type of the active version. Currently the only valid value is
`Workflow::Setup`.
state:
type: string
enum:
- queued
- processing
description: The status of an active version.
original_workflow_id:
type: integer
description: Identifier of the original Workflow version.
name:
type: string
description: The name of the workflow definition.
created_time:
type: string
format: date-time
updated_time:
type: string
format: date-time
runWorkflowRequest:
type: object
title: RunWorkflowRequest
description: ''
nullable: true
additionalProperties: false
properties:
input_parameters:
type: object
additionalProperties: true
description: >-
Include parameters that you want to pass to the workflow. For the
parameters to be recognized and picked up by tasks in the workflow,
you need to define the parameters first.
paymentRunCreateRequest:
type: object
title: PaymentRunCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
apply_credit_memos:
type: boolean
description: If true, any posted credit memos are applied first.
apply_unapplied_payments:
type: boolean
description: If true, any unapplied payments are applied first.
batch:
type: string
description: >-
Identifier of the customer account batch to be included in this
payment run.
bill_cycle_day:
type: string
description: The day of the month to bill multiple customer accounts.
bill_run_id:
type: string
description: The unique identifier of a bill run.
collect_payment:
type: boolean
description: >-
Indicates whether to process electronic payments during the
execution of payment runs. If the Payment user permission
"Process Electronic Payment" is disabled, this field will be
ignored.
currency:
type: string
description: Three-letter ISO currency code.
example: USD
consolidated_payment:
type: boolean
description: >-
If true, a single payment will be collected for all receivables due
on an account.
gateway_id:
type: string
description: Unique identifier for the payment gateway.
payment_run_date:
type: string
format: date-time
example: "2024-08-24 14:15:22Z"
description: >-
The date and time when the scheduled payment run is to be executed,
in `yyyy-mm-dd hh:mm:ssZ` format. The backend will ignore minutes and
seconds in the field value. For example, if you specify `2017-03-01
11:30:37Z` for this value, this payment run will be run at 2017-03-01
11:00:00. <br /> You must specify either the
`payment_run_date` field or the `target_date` field in the request
body. If you specify the `payment_run_date` field, the
scheduced payment run is to be executed on the specified payment run
date. If you specify the `target_date` field, the payment run is
executed immediately after it is created.
target_date:
type: string
format: date
description: >-
The target date used to determine which receivables to be paid in
the payment run. The payments are collected for all
receivables with the due date no later than the target date.
example: '2023-01-01'
paymentRunPatchRequest:
type: object
title: PaymentRunPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
apply_credit_memos:
type: boolean
description: If true, any posted credit memos are applied first.
apply_unapplied_payments:
type: boolean
description: If true, any unapplied payments are applied first.
batch:
type: string
description: >-
Identifier of the customer account batch to be included in this
payment run.
bill_cycle_day:
type: string
description: The day of the month to bill multiple customer accounts.
bill_run_id:
type: string
description: The unique identifier of a bill run.
collect_payment:
type: boolean
description: >-
Indicates whether to process electronic payments during the
execution of payment runs. If the Payment user permission
"Process Electronic Payment" is disabled, this field will be
ignored.
currency:
type: string
description: Three-letter ISO currency code.
example: USD
consolidated_payment:
type: boolean
description: >-
If true, a single payment will be collected for all receivables due
on an account.
gateway_id:
type: string
description: Unique identifier for the payment gateway.
payment_run_date:
type: string
format: date-time
description: >-
The date and time when the scheduled payment run is to be executed,
in `yyyy-mm-dd hh:mm:ssZ` format. The backend will ignore minutes and
seconds in the field value. For example, if you specify `2017-03-01
11:30:37Z` for this value, this payment run will be run at 2017-03-01
11:00:00. <br /> You must specify either the
`payment_run_date` field or the `target_date` field in the request
body. If you specify the `payment_run_date` field, the
scheduced payment run is to be executed on the specified payment run
date. If you specify the `target_date` field, the payment run is
executed immediately after it is created.
target_date:
type: string
format: date
description: >-
The target date used to determine which receivables to be paid in
the payment run. The payments are collected for all
receivables with the due date no later than the target date.
example: '2023-01-01'
paymentRunSummary:
type: object
title: PaymentRunSummary
description: ''
nullable: false
additionalProperties: false
properties:
number_of_errors:
type: integer
description: The number of payments not processed.
number_of_invoices:
type: integer
description: The number of invoices processed.
number_of_payments:
type: integer
description: The number of payments processed.
number_of_credit_memos:
type: integer
description: The number of credit memos processed.
number_of_debit_memos:
type: integer
description: The number of debit memos processed.
number_of_unprocessed_debit_memos:
type: integer
description: The number of unprocessed debit memos.
number_of_unapplied_payments:
type: integer
description: The number of unapplied payments.
number_of_unprocessed_receivables:
type: integer
description: The number of receivables with positive remamining balances.
errors_total:
type: integer
description: The total number of all receivables with payments not processed.
invoices_total:
type: integer
description: The total number of all invoices.
payments_total:
type: integer
description: The total number of all processed and unapplied payments.
unprocessed_receivables_total:
type: integer
description: The total number of positive remaining balances of all receivables.
paymentRun:
type: object
title: PaymentRun
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
apply_credit_memos:
type: boolean
description: If true, any posted credit memos are applied first.
apply_unapplied_payments:
type: boolean
description: If true, any unapplied payments are applied first.
batch:
type: string
description: >-
Identifier of the customer account batch to be included in this
payment run.
consolidate_payment:
type: boolean
description: >-
If true, a single payment will be collected for all receivables due
on an account.
bill_cycle_day:
type: integer
minimum: 0
maximum: 31
description: The day of the month to bill multiple customer accounts.
bill_run_id:
type: string
description: The unique identifier of a bill run.
collect_payment:
type: boolean
description: >-
Indicates whether to process electronic payments during the
execution of payment runs.
currency:
type: string
description: Three-letter ISO currency code.
example: USD
state_transitions:
allOf:
- type: object
properties:
completed:
type: string
readOnly: true
failed:
type: string
readOnly: true
description: >-
The date and time when the payment run executed, in the `yyyy-mm-dd
hh:mm:ss` format.
payment_gateway_id:
type: string
description: Unique identifier for the payment gateway.
payment_collection_date:
type: string
format: date-time
readOnly: true
payment_run_number:
type: string
description: Human-readable identifier for this object.
payment_run_date:
type: string
format: date-time
description: >-
The date and time when the scheduled payment run is to be executed.
target_date:
type: string
format: date
description: >-
The target date used to determine which receivables to be paid in
the payment run. The payments are collected for all
receivables with the due date no later than the target date.
example: '2023-01-01'
state:
type: string
enum:
- processing
- pending
- completed
- canceled
- failed
description: Status of the payment run.
summary:
allOf:
- $ref: '#/components/schemas/paymentRunSummary'
readOnly: true
description: Summary of the payment run.
PaymentRunListResponse:
type: object
title: PaymentRunListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/paymentRun'
fulfillment:
type: object
title: Fulfillment
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
order_line_item_id:
type: string
description: The unique identifier of the associated order line item.
fulfillment_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
fulfillment_date:
type: string
format: date
description: The date of the fulfillment.
example: '2023-01-01'
type:
type: string
enum:
- delivery
- return
description: The type of fulfillment.
quantity:
type: number
description: The number of units of this item.
state:
type: string
enum:
- accepted
- booked
- sent_to_billing
- complete
- canceled
description: The status of the invoice.
target_date:
type: string
format: date
description: >-
All order line items associated with this fulfillment that were
unbilled on or before this date are included in future bill runs.
example: '2022-01-01'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
tracking_number:
type: string
description: The tracking number of the fulfillment.
carrier:
type: string
description: The name of the shipping carrier for this fulfillment.
fulfillment_system:
type: string
description: The fulfillment system for the fulfillment.
external_id:
type: string
description: An external identifier for the fulfillment.
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
location:
additionalProperties: true
type: string
description: The fulfillment location of the fulfillment.
filfillmentListResponse:
type: object
title: FilfillmentListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/fulfillment'
fulfillmentProcessingOption:
type: object
title: FulfillmentProcessingOption
description: ''
nullable: false
additionalProperties: false
properties:
document_date:
type: string
format: date
description: Date on which the billing document is created or paid.
target_date:
type: string
format: date
description: >-
The target date for the order to be picked up by bill run for
billing.
fulfillmentCreateBulkRequest:
type: object
title: FulfillmentCreateBulkRequest
description: ''
nullable: false
additionalProperties: false
properties:
data:
type: array
items:
$ref: '#/components/schemas/fulfillmentRequest'
processing_options:
$ref: '#/components/schemas/fulfillmentProcessingOption'
fulfillmentCreateBulkResponse:
type: object
title: FulfillmentCreateBulkResponse
description: ''
nullable: false
additionalProperties: false
properties:
data:
type: array
items:
$ref: '#/components/schemas/fulfillment'
amount_paid:
type: number
description: The total amount collected by this request.
payment_number:
type: string
description: >-
Human-readable identifier of the payment associated with this
fulfillment.
credit_memo_numbers:
type: array
items:
type: string
description: >-
Human-readable identifiers of any credit memos associated with this
request.
invoice_numbers:
type: array
items:
type: string
description: >-
Human-readable identifiers of any invoices associated with this
request.
fulfillmentCreateRequest:
type: object
title: FulfillmentCreateRequest
allOf:
- $ref: '#/components/schemas/fulfillmentRequest'
properties:
processing_options:
$ref: '#/components/schemas/fulfillmentProcessingOption'
fulfillmentRequest:
type: object
title: FulfillmentRequest
description: ''
nullable: false
additionalProperties: false
properties:
order_line_item_id:
type: string
description: The unique identifier of the associated order line item.
carrier:
type: string
description: The name of the shipping carrier for this fulfillment.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
external_id:
type: string
description: An external identifier for the fulfillment
fulfillment_date:
type: string
format: date
description: The date of the fulfillment.
example: '2022-01-01'
location:
type: string
description: The fulfillment location of the fulfillment.
fulfillment_system:
type: string
description: The fulfillment system for the fulfillment.
type:
type: string
enum:
- delivery
- return
description: The type of fulfillment.
quantity:
type: number
description: The number of units of this item.
state:
type: string
enum:
- accepted
- booked
- sent_to_billing
- complete
- canceled
description: The status of the invoice.
tracking_number:
type: string
description: The tracking number of the fulfillment.
items:
type: array
items:
$ref: >-
#/components/schemas/fulfillmentItemCreateRequestForFulfillmentPost
description: Information of all fulfillment items.
required:
- order_line_item_id
- fulfillment_date
- quantity
fulfillmentPatchRequest:
type: object
title: FulfillmentPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
order_line_item_id:
type: string
description: The unique identifier of the associated order line item.
target_date:
type: string
format: date
description: >-
All order line items associated with this fulfillment that were
unbilled on or before this date are included in future bill runs.
example: '2022-01-01'
carrier:
type: string
description: The name of the shipping carrier for this fulfillment.
custom_fields:
$ref: '#/components/schemas/customFields'
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
revenue:
allOf:
- $ref: '#/components/schemas/revenue'
external_id:
type: string
description: An external identifier for the fulfillment.
fulfillment_date:
type: string
format: date
description: The date of the fulfillment.
example: '2023-01-01'
location:
type: string
description: The fulfillment location of the fulfillment
fulfillment_system:
type: string
description: The fulfillment system for the fulfillment
type:
type: string
enum:
- delivery
- return
description: The type of fulfillment.
quantity:
type: number
description: The number of units of this item.
state:
type: string
enum:
- accepted
- booked
- sent_to_billing
- complete
- canceled
description: The status of the invoice.
tracking_number:
type: string
description: The tracking number of the fulfillment.
fulfillmentItemCreateRequestForFulfillmentPost:
type: object
title: FulfillmentItemCreateRequestForFulfillmentPost
description: ''
nullable: false
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
fulfillment_item_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
custom_fields:
$ref: '#/components/schemas/customFields'
fulfillmentItemCreateRequest:
type: object
title: FulfillmentItemCreateRequest
description: ''
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
fulfillment_item_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
custom_fields:
$ref: '#/components/schemas/customFields'
fulfillment_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
required:
- fulfillment_number
fulfillmentItemCreateBulkRequest:
type: object
title: FulfillmentItemCreateBulkRequest
description: ''
nullable: false
additionalProperties: false
properties:
data:
type: array
items:
$ref: '#/components/schemas/fulfillmentItemCreateRequest'
fulfillmentItemBulkResponse:
type: object
title: FulfillmentItemBulkResponse
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Human-readable identifier of the fulfillment id.
fulfillmentItemCreateBulkResponse:
type: object
title: FulfillmentItemCreateBulkResponse
description: ''
nullable: false
additionalProperties: false
properties:
data:
type: array
items:
$ref: '#/components/schemas/fulfillmentItemBulkResponse'
fulfillmentItem:
type: object
title: FulfillmentItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
fulfillment_item_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
fulfillment_id:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
filfillmentItemListResponse:
type: object
title: FilfillmentItemListResponse
description: ''
nullable: false
additionalProperties: false
properties:
next_page:
type: string
nullable: true
data:
type: array
items:
$ref: '#/components/schemas/fulfillmentItem'
fulfillmentItemPatchRequest:
type: object
title: FulfillmentItemPatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
fulfillment_item_number:
type: string
description: Human-readable identifier for the object. It can be user-supplied.
custom_fields:
$ref: '#/components/schemas/customFields'
paymentScheduleItemPaymentOption:
type: object
title: PaymentScheduleItemPaymentOption
description: ''
nullable: false
additionalProperties: false
properties:
detail:
type: object
additionalProperties:
type: string
example:
key: value
type:
type: string
paymentScheduleItemPayments:
type: object
title: PaymentScheduleItemPayments
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier of the payment schedule item.
paymentScheduleItemCreateRequest:
type: object
title: PaymentScheduleItemCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
payment_schedule_id:
type: string
description: ID of a payment schedule.
payment_schedule_number:
type: string
description: Number of the payment schedule.
account_id:
type: string
description: >-
Unique identifier of the customer account the payment schedule
belongs to.
example: 8ad093f27d6eee80017d6effd7a66759
amount:
type: number
description: The amount to be collected by this payment schedule item.
currency:
type: string
description: >-
Currency of the payment schedule. The default value is the account's
default currency. This field will be ignored when items is
specified.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of payment schedule item
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. The default
value is the account's default payment gateway ID. If no payment
gateway ID is found on the customer account level, the default value
will be the tenant's default payment gateway ID. This field will be
ignored when `items` is specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. The default value is the account's default
payment method ID. This field will be ignored when `items` is
specified.
example: 8a95b1946b6aeac8718c32aab8c395f
scheduled_date:
type: string
format: date
description: The scheduled date of collection.
example: '2022-01-01'
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is 0. If the
payment run_hour and scheduled_date are backdated, the system will
collect the payment when the next run_hour occurs.
custom_fields:
$ref: '#/components/schemas/customFields'
payment_options:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemPaymentOption'
description: >-
Container for the payment options, which describe the transactional
level rules for processing payments. Currently, only the
`gateway_options` type is supported. Payment schedule
`payment_options` take precedence over payment schedule item
`payment_options`.
required:
- payment_schedule_id
paymentScheduleItemLink:
type: object
title: PaymentScheduleItemLink
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier of the payment schedule item.
paymentScheduleItemUnlink:
type: object
title: PaymentScheduleItemUnlink
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier of the payment schedule item.
paymentScheduleItemPatch:
type: object
title: PaymentScheduleItemPatch
description: ''
nullable: false
additionalProperties: false
properties:
payment_schedule_id:
type: string
description: ID of the payment schedule.
payment_schedule_number:
type: string
description: Number of the payment schedule.
amount:
type: number
description: The amount to be collected by this payment schedule item.
currency:
type: string
description: >-
Currency of the payment schedule. The default value is the account's
default currency. This field will be ignored when items is
specified.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of payment schedule item
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. The default
value is the account's default payment gateway ID. If no payment
gateway ID is found on the customer account level, the default value
will be the tenant's default payment gateway ID. This field will be
ignored when `items` is specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. The default value is the account's default
payment method ID. This field will be ignored when `items` is
specified.
example: 8a95b1946b6aeac8718c32aab8c395f
scheduled_date:
type: string
format: date
description: The scheduled date of collection.
example: '2022-01-01'
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is 0. If the
payment run_hour and scheduled_date are backdated, the system will
collect the payment when the next run_hour occurs.
custom_fields:
$ref: '#/components/schemas/customFields'
payment_options:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemPaymentOption'
description: >-
Container for the payment options, which describe the transactional
level rules for processing payments. Currently, only the
`gateway_options` type is supported. Payment schedule
`payment_options` take precedence over payment schedule item
`payment_options`.
link:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemLink'
unlink:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemUnlink'
paymentScheduleItemRetry:
type: object
title: PaymentScheduleItemRetry
description: ''
nullable: false
additionalProperties: false
properties:
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. The default
value is the account's default payment gateway ID. If no payment
gateway ID is found on the customer account level, the default value
will be the tenant's default payment gateway ID. This field will be
ignored when `items` is specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. The default value is the account's default
payment method ID. This field will be ignored when `items` is
specified.
example: 8a95b1946b6aeac8718c32aab8c395f
paymentScheduleItemRequest:
type: object
title: PaymentScheduleItemRequest
description: ''
nullable: false
additionalProperties: false
properties:
amount:
type: number
description: The amount to be collected by this payment schedule item.
currency:
type: string
description: >-
Three-letter ISO currency code. Once the currency is set for an
account, it cannot be updated.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
gateway_id:
type: string
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: Identifier of the payment method on the customer account.
example: 8a95b1946b6aeac8718c32aab8c395f
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is `0`. If
the payment `run_hour` and `scheduled_date` are backdated, the
system will collect the payment when the next `run_hour` occurs.
scheduled_date:
type: string
format: date
description: The scheduled date of the payment collection.
example: '2022-01-01'
custom_fields:
$ref: '#/components/schemas/customFields'
paymentSchedulePaymentOptionRequest:
type: object
title: PaymentSchedulePaymentOptionRequest
description: ''
nullable: false
additionalProperties: false
properties:
detail:
type: object
additionalProperties:
type: string
example:
key: value
type:
type: boolean
paymentScheduleBillingDocumentResponse:
type: object
title: PaymentScheduleBillingDocumentResponse
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier of an invoice or debit memo billing document.
type:
type: string
enum:
- invoice
- debit_memo
description: The type of billing document. The default is `invoice`.
paymentScheduleBillingDocumentRequest:
type: object
title: PaymentScheduleBillingDocumentRequest
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
description: Unique identifier of an invoice or debit memo billing document.
type:
type: string
enum:
- invoice
- debit_memo
description: The type of billing document. The default is `invoice`.
billing_document_number:
type: string
description: Document number of an invoice or debit memo billing document.
paymentScheduleItem:
type: object
title: PaymentScheduleItem
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: >-
Unique identifier of the customer account the payment schedule
belongs to.
example: 8ad093f27d6eee80017d6effd7a66759
amount:
type: number
description: The amount to be collected by this payment schedule item.
balance:
type: number
description: The remaining balance of payment schedule item.
billing_document:
allOf:
- $ref: '#/components/schemas/paymentScheduleBillingDocumentResponse'
description: >-
The billing document with which the payment schedule is associated.
If you have the Standalone Payment feature enabled, you can leave
this field blank and set standalone to true to create standalone
payments. You can also choose to create unapplied payments by
leaving this object blank and setting standalone to false. If
Standalone Payment is not enabled, leaving this object unspecified
will create unapplied payments.
cancellation_reason:
type: string
description: The reason for the cancellation of payment schedule item.
currency:
type: string
description: >-
Currency of the payment schedule. The default value is the account's
default currency. This field will be ignored when items is
specified.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of payment schedule item
payment_schedule_item_number:
type: string
description: Number of the payment schedule item.
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. The default
value is the account's default payment gateway ID. If no payment
gateway ID is found on the customer account level, the default value
will be the tenant's default payment gateway ID. This field will be
ignored when `items` is specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. The default value is the account's default
payment method ID. This field will be ignored when `items` is
specified.
example: 8a95b1946b6aeac8718c32aab8c395f
payment_option_id:
type: string
description: ID of the payment option.
payment_schedule_id:
type: string
description: ID of the payment schedule.
payment_schedule_number:
type: string
description: Number of the payment schedule.
payments:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemPayments'
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is 0. If the
payment run_hour and scheduled_date are backdated, the system will
collect the payment when the next run_hour occurs.
scheduled_date:
type: string
format: date
description: The scheduled date of collection.
example: '2022-01-01'
standalone:
type: boolean
description: >-
Indicates whether the payments created by the payment schedule are
standalone payments or not. When setting to true, standalone
payments will be created. When setting to false, you can either
specify a billing document, or not specifying any billing documents.
In the later case, unapplied payments will be created. If set to
null, standalone payments will be created. Note: This parameter is
only available if standalone payments are enabled in your tenant. Do
not include this parameter if standalone payment have not been
enabled in your tenant. If standalone payments are enabled, the
default value is true.
state:
type: string
enum:
- pending
- canceled
- complete
- error
description: >-
The status of the payment schedule item. active: there are
unprocessed payment schedule items. canceled: the payment schedule
has been canceled. complete: the payment schedule is complete and
all items have been processed.
error_message:
type: string
description: >-
An error message indicating why payment collection failed for this
payment schedule item.
payment:
allOf:
- $ref: '#/components/schemas/payment'
readOnly: true
description: List of customer payments.
payment_schedule:
allOf:
- $ref: '#/components/schemas/paymentSchedule'
readOnly: true
description: Payment schedule record.
paymentScheduleCreateRequest:
type: object
title: PaymentScheduleCreateRequest
description: ''
nullable: false
additionalProperties: false
properties:
account_id:
type: string
description: >-
Unique identifier of the customer account the payment schedule
belongs to.
account_number:
type: string
description: >-
Account number of the customer account the payment schedule belongs
to.
billing_document:
allOf:
- $ref: '#/components/schemas/paymentScheduleBillingDocumentRequest'
description: >-
The billing document with which the payment schedule is associated.
Note: This field is optional. If you have the Standalone Payment
feature enabled, you can leave this field blank and set standalone
to true to create standalone payments. You can also choose to create
unapplied payments by leaving this object blank and setting
standalone to false. If Standalone Payment is not enabled, leaving
this object unspecified will create unapplied payments.
currency:
type: string
description: >-
Currency of the payment schedule. Note: This field is optional. The
default value is the account's default currency. This field will be
ignored when items is specified.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
items:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItemRequest'
description: Container for payment schedule items.
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. Note: This field
is optional. The default value is the account's default payment
gateway ID. If no payment gateway ID is found on the customer
account level, the default value will be the tenant's default
payment gateway ID. This field will be ignored when items is
specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_gateway_number:
type: string
description: >-
The payment gateway number of the payment gateway used to collect
scheduled payments.
payment_method_number:
type: string
description: >-
The payment method number of the payment method to be used to
collect payments.
payment_method_id:
type: string
description: >-
ID of the payment method. Note: This field is optional. The default
value is the account's default payment method ID. This field will be
ignored when items is specified.
example: 8a95b1946b6aeac8718c32aab8c395f
payment_schedule_number:
type: string
description: Number of the payment schedule.
payment_options:
type: array
items:
$ref: '#/components/schemas/paymentSchedulePaymentOptionRequest'
description: >-
Container for the payment options, which describe the transactional
level rules for processing payments. Currently, only the
gateway_options type is supported. Payment schedule payment_options
take precedence over payment schedule item payment_options.
standalone:
type: boolean
description: >-
Indicates whether the payments created by the payment schedule are
standalone payments or not.
When setting to `true`, standalone payments will be created. When setting to `false`, you can either specify a billing document, or not specifying any billing documents. In the latter case, unapplied payments will be created. If set to `null`, standalone payments will be created.
**Note**: This parameter is only available if standalone payments are enabled in your tenant. The default value is `true` if standalone payments are enabled in your tenant.
start_date:
type: string
format: date
description: >-
The date of the first scheduled payment collection. Note: This
parameter is required when `items` is not specified. This parameter
will be ignored when `items` is specified.
example: '2023-01-01'
prepayment:
type: boolean
description: >-
Indicates whether the payments created by the payment schedule will
be used as reserved payments. This field will only be available if
the prepaid cash drawdown permission is enabled. See <a
href="https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Bill_for_usage_or_prepaid_products/Advanced_Consumption_Billing/Prepaid_with_Drawdown"
target="_blank">Prepaid Cash with Drawdown for more information.</a>
period:
enum:
- week
- month
- biweekly
description: Unit in which term duration is defined. One of week or month.
amount:
type: number
description: The amount of each payment schedule item in the payment schedule.
total_amount:
type: number
description: The total amount to be collected by the payment schedule.
number_of_payments:
type: integer
description: >-
The number of payment schedule items to be created for this payment
schedule.
custom_fields:
$ref: '#/components/schemas/customFields'
paymentSchedule:
type: object
title: PaymentSchedule
description: ''
nullable: false
additionalProperties: false
properties:
id:
type: string
readOnly: true
description: Unique identifier for the object.
updated_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who last updated the object
updated_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was last updated in ISO 8601 UTC
format.
created_by_id:
type: string
readOnly: true
description: Unique identifier of the Zuora user who created the object
created_time:
type: string
format: date-time
readOnly: true
description: >-
The date and time when the object was created in ISO 8601 UTC
format.
custom_fields:
type: object
title: CustomFields
description: >-
Set of user-defined fields associated with this object. Useful for
storing additional information about the object in a structured
format.
x-extra-field-annotation: '@JsonAdapter(CustomFieldAdapter.class)'
additionalProperties:
type: string
custom_objects:
type: object
additionalProperties:
oneOf:
- $ref: '#/components/schemas/listCustomObjectResponse'
- $ref: '#/components/schemas/custom_object'
readOnly: true
description: The custom objects associated with a Zuora standard object.
account_id:
type: string
description: >-
Unique identifier of the customer account the payment schedule
belongs to.
account_number:
type: string
description: >-
Account number of the customer account the payment schedule belongs
to.
amount:
type: number
description: The amount of each payment schedule item in the payment schedule.
period:
enum:
- week
- month
- biweekly
description: Unit in which term duration is defined. One of week or month.
billing_document:
allOf:
- $ref: '#/components/schemas/paymentScheduleBillingDocumentResponse'
description: >-
The billing document with which the payment schedule is associated.
Note: This field is optional. If you have the Standalone Payment
feature enabled, you can leave this field blank and set standalone
to true to create standalone payments. You can also choose to create
unapplied payments by leaving this object blank and setting
standalone to false. If Standalone Payment is not enabled, leaving
this object unspecified will create unapplied payments.
currency:
type: string
description: >-
Currency of the payment schedule. Note: This field is optional. The
default value is the account's default currency. This field will be
ignored when items is specified.
example: USD
description:
type: string
description: >-
An arbitrary string attached to the object. Often useful for
displaying to users.
example: description of test account
items:
type: array
items:
$ref: '#/components/schemas/paymentScheduleItem'
number_of_payments:
type: integer
description: >-
The number of payment schedule items to be created for this payment
schedule.
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. Note: This field
is optional. The default value is the account's default payment
gateway ID. If no payment gateway ID is found on the customer
account level, the default value will be the tenant's default
payment gateway ID. This field will be ignored when items is
specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. Note: This field is optional. The default
value is the account's default payment method ID. This field will be
ignored when items is specified.
example: 8a95b1946b6aeac8718c32aab8c395f
payment_schedule_number:
type: string
description: Number of the payment schedule.
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is 0. If the
payment run_hour and scheduled_date are backdated, the system will
collect the payment when the next run_hour occurs.
standalone:
type: boolean
description: >-
Indicates whether the payments created by the payment schedule are
standalone payments or not.
When setting to `true`, standalone payments will be created. When setting to `false`, you can either specify a billing document, or not specifying any billing documents. In the latter case, unapplied payments will be created. If set to `null`, standalone payments will be created.
**Note**: This parameter is only available if standalone payments are enabled in your tenant. The default value is `true` if standalone payments are enabled in your tenant.
start_date:
type: string
format: date
description: >-
The date of the first scheduled payment collection. Note: This
parameter is required when `items` is not specified. This parameter
will be ignored when `items` is specified.
example: '2023-01-01'
total_amount:
type: number
description: The total amount to be collected by the payment schedule.
custom:
type: boolean
description: >-
If it is set to `true`, the payment schedule is a custom payment
schedule.
next_payment_date:
type: string
format: date
description: The date of the next scheduled payment.
example: '2022-01-01'
recent_payment_date:
type: string
format: date
description: The date of the most recent scheduled payment.
example: '2022-01-01'
state:
type: string
enum:
- active
- canceled
- complete
description: >-
The status of the payment schedule. active: there are unprocessed
payment schedule items. canceled: the payment schedule has been
canceled. complete: the payment schedule is complete and all items
have been processed.
total_payments_errored:
type: integer
description: The total number of failed payments.
total_payments_processed:
type: integer
description: The total number of payments processed.
payment_options:
type: array
items:
$ref: '#/components/schemas/paymentSchedulePaymentOptionRequest'
description: >-
Container for the payment options, which describe the transactional
level rules for processing payments. Currently, only the
gateway_options type is supported. Payment schedule payment_options
take precedence over payment schedule item payment_options.
prepayment:
type: boolean
description: >-
Indicates whether the payments created by the payment schedule will
be used as reserved payments. This field will only be available if
the prepaid cash drawdown permission is enabled. See <a
href="https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Bill_for_usage_or_prepaid_products/Advanced_Consumption_Billing/Prepaid_with_Drawdown"
target="_blank">Prepaid Cash with Drawdown for more information.</a>
paymentSchedulePatchRequest:
type: object
title: PaymentSchedulePatchRequest
description: ''
nullable: false
additionalProperties: false
properties:
currency:
type: string
description: >-
Currency of the payment schedule. Note: This field is optional. The
default value is the account's default currency. This field will be
ignored when items is specified.
example: USD
number_of_payments:
type: integer
description: >-
The number of payment schedule items to be created for this payment
schedule.
payment_gateway_id:
type: string
description: >-
ID of the payment gateway used to collect payments. Note: This field
is optional. The default value is the account's default payment
gateway ID. If no payment gateway ID is found on the customer
account level, the default value will be the tenant's default
payment gateway ID. This field will be ignored when items is
specified.
example: 8ad093f27d6eee80017d6effd7a66759
payment_method_id:
type: string
description: >-
ID of the payment method. Note: This field is optional. The default
value is the account's default payment method ID. This field will be
ignored when items is specified.
example: 8a95b1946b6aeac8718c32aab8c395f
payment_method_number:
type: string
description: >-
The payment method number of the payment method to be used to
collect payments.
run_hour:
type: integer
minimum: 0
maximum: 23
description: >-
At which hour in the day in the tenant's timezone this payment will
be collected. Available values:[0,1,2,~,22,23]. If the time
difference between your tenant’s timezone and the timezone where
Zuora servers are located is not in full hours, for example, 2.5
hours, the payment schedule items will be triggered half an hour
later than your scheduled time. The default value is `0`. If
the payment `run_hour` and `scheduled_date` are backdated, the
system will collect the payment when the next `run_hour` occurs.
custom_fields:
$ref: '#/components/schemas/customFields'
payment_options:
type: array
items:
$ref: '#/components/schemas/paymentSchedulePaymentOptionRequest'
description: >-
Container for the payment options, which describe the transactional
level rules for processing payments. Currently, only the
gateway_options type is supported. Payment schedule payment_options
take precedence over payment schedule item payment_options.
start_date:
type: string
format: date
description: >-
The date of the first scheduled payment collection. Note: This
parameter is required when `items` is not specified. This parameter
will be ignored when `items` is specified.
example: '2023-01-01'
amount:
type: number
description: The amount of each payment schedule item in the payment schedule.
period:
enum:
- week
- month
- biweekly
description: Unit in which term duration is defined. One of week or month.
paymentScheduleCancel:
type: object
title: PaymentScheduleCancel
description: ''
nullable: false
additionalProperties: false
properties:
cancel_date:
type: string
format: date
description: The date on which the payment schdule is canceled.
example: '2022-09-01'
required:
- cancel_date
prepaidBalance:
type: object
title: PrepaidBalance
description: ''
nullable: false
additionalProperties: false
properties:
prepaid_UOM:
type: string
description: Unit of measure for the prepaid balance.
start_date:
type: string
format: date
description: Start date of the fund effective period.
example: '2022-01-01'
end_date:
type: string
format: date
description: End date of the fund effective period.
example: '2023-01-01'
total_balance:
type: number
description: 'The funded balance, which is the total units of the fund. '
remaining_balance:
type: number
description: >-
Remaining balance on the fund, which is the remaining units of the
fund.
transactions:
type: array
items:
$ref: '#/components/schemas/prepaidBalanceTransaction'
readOnly: true
description: An array of prepaid balance transactions
validityPeriod:
type: object
title: ValidityPeriod
description: ''
nullable: false
additionalProperties: false
properties:
prepaid_UOM:
type: string
description: Unit of measure for the prepaid balance.
start_date:
type: string
format: date
description: Start date of the fund effective period.
example: '2022-01-01'
end_date:
type: string
format: date
description: End date of the fund effective period.
example: '2023-01-01'
total_balance:
type: number
description: 'The funded balance, which is the total units of the fund. '
remaining_balance:
type: number
description: >-
Remaining balance on the fund, which is the remaining units of the
fund.
overage_rated_amount:
type: number
overage_rated_quantity:
type: number
transactions:
type: array
items:
$ref: '#/components/schemas/prepaidBalanceTransaction'
readOnly: true
description: >-
An array of prepaid balance transactions for a specific validity
period
prepaidBalances:
type: object
title: PrepaidBalances
description: ''
nullable: false
additionalProperties: false
properties:
validity_periods:
type: array
items:
$ref: '#/components/schemas/validityPeriod'
readOnly: true
description: An array of prepaid balance validity periods
prepaidBalanceTransaction:
type: object
title: PrepaidBalanceTransaction
description: ''
nullable: false
additionalProperties: false
properties:
transaction_date:
type: string
description: Date on which the transaction occurs.
type:
type: string
enum:
- prepayment
- drawdown
description: >-
An action that increases or decreases its associated prepaid
balance.
quantity:
type: number
description: Quantity of the prepaid balance transaction.
error:
type: object
title: Error
description: ''
nullable: false
additionalProperties: false
properties:
code:
type: string
parameter:
type: string
message:
type: string
errorResponse:
type: object
title: ErrorResponse
description: ''
nullable: false
additionalProperties: false
properties:
type:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/error'
retryable:
type: boolean
paths:
/accounts:
get:
operationId: getAccounts
summary: List accounts
tags:
- Accounts
description: >-
Returns a dictionary with a data property that contains an array of
accounts, starting after the cursor, if used. Each entry in the array is
a separate account object. If no more accounts are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: payment_methods.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payments.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: billing_documents.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: sold_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: default_payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: usage_records.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: invoices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: debit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/accounts' --header
'Authorization: Bearer d8a7f4d2a5ef4c3eba8618cf99593e26'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
ListAccountResponse accountListResponse =
zuoraClient.accounts().getAccounts(null,Collections.singletonList("bill_to"),null);
System.out.println(accountListResponse);
- lang: JavaScript
label: Node
source: |-
const accountsResponse = await zuoraClient.accounts.getAccounts({
filter: [
'batch.EQ:Batch1',
],
expand: [
'subscriptions',
]
})
console.log(accountsResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/listAccountResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createAccount
summary: Create an account
tags:
- Accounts
description: Creates a new account object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/accountCreateRequest'
example:
name: Amy Lawrence Account
currency: USD
bill_to:
first_name: Amy
last_name: Lawrence
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: USA
postal_code: '94065'
work_phone: (888) 976-9056
work_email: amy.lawrence@gmail.com
sold_to:
first_name: Amy
last_name: Lawrence
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
state: California
country: USA
postal_code: '94065'
work_phone: (888) 976-9056
work_email: amy.lawrence@gmail.com
custom_fields:
field__c: custom field value
payment_terms: Due Upon Receipt
tax_certificate:
start_date: '2022-01-01'
end_date: '2023-01-01'
state: pending
sequence_set_id: 8f64d4d793733fb0be444ff770a932c7
billing_document_settings:
additional_email:
- jane.doe@gmail.com
- james.lawerence@gmail.com
email_documents: true
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: payment_methods.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payments.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: billing_documents.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: sold_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: default_payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: usage_records.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: invoices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: debit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/accounts --header
'Authorization: Bearer 8d17d8e8cc36419998a205896d670ed2'
--header 'Content-Type: application/json' --data '{
"name": "Amy Lawrence",
"bill_to": {
"first_name": "Amy",
"last_name": "Lawrence",
"address": {
"country": "USA",
"state": "CA"
}
},
"currency": "USD"
}'
- lang: Java
label: Java
source: >-
AccountContactCreateRequest contactCreateRequest = new
AccountContactCreateRequest()
.firstName("Amy")
.lastName("Lawrence")
.address(new Address()
.country("USA")
.state("CA"));
AccountCreateRequest accountCreateRequest = new
AccountCreateRequest()
.name("Amy Lawrence")
.billTo(contactCreateRequest)
.currency("USD");
Account newAccount =
zuoraClient.accounts().createAccount(accountCreateRequest);
- lang: JavaScript
label: Node
source: >-
const contactCreateRequest = {
first_name: "Amy",
last_name: "Lawrence",
address: {
country: "USA",
state: "CA"
}
};
const accountCreateRequest = {
name: "Amy Lawrence's account",
bill_to: contactCreateRequest,
currency: "USD"
};
const newAccount = await
zuoraClient.accounts.createAccount(accountCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/account'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/accounts/{account_id}:
get:
operationId: getAccount
summary: Retrieve an account
tags:
- Accounts
description: Retrieves the account with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: payment_methods.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payments.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: billing_documents.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: sold_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: default_payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: usage_records.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: invoices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: debit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: account_id
required: true
schema:
type: string
description: Identifier for the account, either `account_number` or `account_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/accounts/2c92c0f86a8dd422016a9e7a70116b0d
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Account accountResponse =
zuoraClient.accounts().getAccount(newAccount.getId(),null);
System.out.println(accountResponse);
- lang: JavaScript
label: Node
source: >-
const accountResponse = await
zuoraClient.accounts.getAccount('RC-00020836');
console.log(accountResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/account'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:07:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-0002048901234
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Amy Lawrence Account
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateAccount
summary: Update an account
tags:
- Accounts
description: >-
Updates the specified account by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/accountPatchRequest'
example:
name: Johnny Smith
custom_fields:
field__c: custom field value
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: payment_methods.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payments.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: billing_documents.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: sold_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: default_payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: usage_records.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: invoices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: debit_memos.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: account_id
required: true
schema:
type: string
description: Identifier for the account, either `account_number` or `account_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/accounts/2c92c0f86a8dd422016a9e7a70116b0d
--header 'Authorization: Bearer
06a297740b184fc384bc57cbe8a04e53' --header 'Content-Type:
application/json' --data '{
"name": "Bella's Account",
"crm_id": "A12345"
}'
- lang: Java
label: Java
source: >-
Account oldAccount =
zuoraClient.accounts().getAccount("8ad0950c82aa847f0182ae9563f46b84",
null);
AccountPatchRequest accountPatchRequest = new AccountPatchRequest()
.name("Updated Account")
.crmId("A12345");
Account updatedAccount =
zuoraClient.accounts().updateAccount(oldAccount.getId(),accountPatchRequest);
- lang: JavaScript
label: Node
source: >-
const accountPatchRequest = {
name: 'Updated Account Name',
bill_to: {
first_name: "Bella",
last_name: "Lawrence",
address: {
country: "USA",
state: "NY"
}
}
};
const updatedAccount = await
zuoraClient.accounts.updateAccount('8ad0950c83927b4301839e70a6611e0c',
accountPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/account'
example:
id: 8ad085518262bc17018265525eab3696
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:12:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:07:53-07:00'
custom_fields:
field__c: custom field value
account_number: RC-00020489
billing_document_settings:
email_documents: true
print_documents: false
invoice_template_id: 8f64d4d754739d85d0346e00ef77e50d
additional_email:
- jane.doe@gmail.com
- ' james.lawerence@gmail.com'
batch: Batch1
bill_cycle_day: 0
name: Johnny Smith
payment_terms: Due Upon Receipt
auto_pay: false
currency: USD
enabled: true
remaining_debit_memo_balance: 0
remaining_invoice_balance: 0
remaining_credit_memo_balance: 0
remaining_payment_balance: 0
bill_to_id: 8ad085518262bc17018265525ebb3697
sold_to_id: 8ad085518262bc17018265525ec43699
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteAccount
summary: Delete an account
tags:
- Accounts
description: Permanently deletes an account. It cannot be undone.
parameters:
- in: path
name: account_id
required: true
schema:
type: string
description: Identifier for the account, either `account_number` or `account_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/accounts/2c92c0f86a8dd422016a9e7a70116b0d'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.accounts().deleteAccount(newAccount.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteAccountResponse = await
zuoraClient.accounts.deleteAccount('8ad087e284427311018447079d9e4efe');
console.log(deleteAccountResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/accounts/{account_id}/bill:
post:
operationId: generateBillingDocuments
summary: Generate billing documents for an account
tags:
- Accounts
description: Creates billing documents for an account.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/generateBillingDocumentsAccountRequest'
example:
target_date: '2023-12-01'
subscription_ids:
- 8ad0940886748c1501867a78a9444790
- 8ad08cbd86747d0801867a7a7f8445a4
document_date: '2023-02-21'
required: true
parameters:
- in: path
name: account_id
required: true
schema:
type: string
description: Identifier for the account, either `account_number` or `account_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/accounts/RC-00021202/bill
--header 'Authorization: Bearer
bf4e7bec20f443cc82388e37193ee428' --header 'Content-Type:
application/json' --data '{
"target_date": "2023-06-01",
"subscription_ids": [
"8ad08cbd878f3de0018790e028c23dc5"
],
"document_date": "2023-02-21"
}'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/generateBillingDocumentsAccountResponse'
example:
invoices:
next_page: null
data:
- id: 8ad0934e86748c2001867a7f3c321612
invoice_number: INV00009222
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-02-22T11:00:04-08:00'
updated_time: '2023-02-22T11:00:06-08:00'
state_transitions: {}
state: draft
account_id: 8ad09b2186748c1701867a77cdab118e
items:
next_page: null
data:
- amount: 0
created_by_id: 2c92c0946a6dffc0016a7faab604299b
discount_item: false
created_time: '2023-02-22T11:00:06-08:00'
custom_fields:
SFDCSynced__c: 'False'
description: >-
Per minute usage price with tiered and overage
pricing
id: 8ad0934e86748c2001867a7f43da18af
invoice_id: 8ad0934e86748c2001867a7f3c321612
sku: SKU-00011670
name: Usage Price
quantity: 0
remaining_balance: 0
service_end: '2023-11-30'
service_start: '2023-11-01'
subscription_id: 8ad0940886748c1501867a78a9444790
subscription_item_id: 8ad0940886748c1501867a78ada84871
tax: 0
tax_inclusive: false
unit_amount: 0
unit_of_measure: Each
updated_time: '2023-02-22T11:00:06-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
- amount: 0
created_by_id: 2c92c0946a6dffc0016a7faab604299b
discount_item: false
created_time: '2023-02-22T11:00:06-08:00'
custom_fields:
SFDCSynced__c: 'False'
description: >-
Per minute usage price with tiered and overage
pricing
id: 8ad0934e86748c2001867a7f43d718ae
invoice_id: 8ad0934e86748c2001867a7f3c321612
sku: SKU-00011670
name: Usage Price
quantity: 0
remaining_balance: 0
service_end: '2023-10-31'
service_start: '2023-10-01'
subscription_id: 8ad0940886748c1501867a78a9444790
subscription_item_id: 8ad0940886748c1501867a78ada84871
tax: 0
tax_inclusive: false
unit_amount: 0
unit_of_measure: Each
updated_time: '2023-02-22T11:00:06-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
total: 611600
subtotal: 611600
tax: 0
balance: 611600
paid: false
past_due: true
document_date: '2023-02-21'
due_date: '2023-02-21'
custom_fields:
InvoiceWFProcessed__c: '0'
EmailSentWorkflow__c: Unprocessed
LateFeeApplied__c: 'False'
- id: 8ad0934e86748c2001867a7f3b58160f
invoice_number: INV00009221
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-02-22T11:00:04-08:00'
updated_time: '2023-02-22T11:00:06-08:00'
state_transitions: {}
state: draft
account_id: 8ad09b2186748c1701867a77cdab118e
items:
next_page: null
data:
- amount: 10
created_by_id: 2c92c0946a6dffc0016a7faab604299b
discount_item: false
created_time: '2023-02-22T11:00:04-08:00'
custom_fields:
SFDCSynced__c: 'False'
description: Monthly fee of the Basic Monthly plan
id: 8ad0934e86748c2001867a7f3cb71626
invoice_id: 8ad0934e86748c2001867a7f3b58160f
sku: SKU-00011814
name: Basic Monthly Fee
quantity: 1
remaining_balance: 10
service_end: '2023-12-21'
service_start: '2023-11-22'
subscription_id: 8ad08cbd86747d0801867a7a7f8445a4
subscription_item_id: 8ad08cbd86747d0801867a7a7fad45ad
tax: 0
tax_inclusive: false
unit_amount: 10
updated_time: '2023-02-22T11:00:04-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
- amount: 10
created_by_id: 2c92c0946a6dffc0016a7faab604299b
discount_item: false
created_time: '2023-02-22T11:00:04-08:00'
custom_fields:
SFDCSynced__c: 'False'
description: Monthly fee of the Basic Monthly plan
id: 8ad0934e86748c2001867a7f3cb51625
invoice_id: 8ad0934e86748c2001867a7f3b58160f
sku: SKU-00011814
name: Basic Monthly Fee
quantity: 1
remaining_balance: 10
service_end: '2023-11-21'
service_start: '2023-10-22'
subscription_id: 8ad08cbd86747d0801867a7a7f8445a4
subscription_item_id: 8ad08cbd86747d0801867a7a7fad45ad
tax: 0
tax_inclusive: false
unit_amount: 10
updated_time: '2023-02-22T11:00:04-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
total: 200
subtotal: 200
tax: 0
balance: 200
paid: false
past_due: true
document_date: '2023-02-21'
due_date: '2023-02-21'
custom_fields:
InvoiceWFProcessed__c: '0'
EmailSentWorkflow__c: Unprocessed
LateFeeApplied__c: 'False'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/accounts/{account_id}/preview:
post:
operationId: previewAccount
summary: Preview an account
tags:
- Accounts
description: >-
Generates a preview of future invoice and credit memo items for a
customer account. Previewing a customer account shows you
how much a single customer will be invoiced from the most recent invoice
to a specific end of term date in the future. <br/> Previewing
a customer account only calculates taxes for charges if you use <a
href='https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax'
target='_blank'>Zuora Tax</a> and the price associated with the invoice
item is tax inclusive; otherwise, it does not calculate taxes.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/accountPreviewRequest'
required: true
parameters:
- in: path
name: account_id
required: true
schema:
type: string
description: Identifier for the account, either `account_number` or `account_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/accounts/8ad08dc9877a58d201877b3b39393c44/preview'
--header 'Authorization: Bearer
9cddcab8242046c1b7c92e46f8451480' --header 'Content-Type:
application/json' --data '{
"target_date": "2023-12-01"
}'
- lang: Java
label: Java
source: >2-
AccountPreviewRequest accountPreviewRequest = new
AccountPreviewRequest()
.target_date("2023-12-01");
Account newAccount =
zuoraClient.accounts().previewAccount("8ad08dc9877a58d201877b3b39393c44",
accountPreviewRequest);
- lang: JavaScript
label: Node
source: >2-
const accountPreviewRequest = {
target_date: '2023-12-01'
};
const newAccount = await
zuoraClient.accounts.previewAccount('8ad08dc9877a58d201877b3b39393c44',accountPreviewRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/accountPreviewResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/billing_documents/{billing_document_id}:
get:
operationId: getBillingDocument
summary: Retrieve a billing document
tags:
- Billing Documents
description: Retrieves the billing document with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: billing_document_id
required: true
schema:
type: string
description: >-
Identifier for the billingDocument, either `billing_document_number`
or `billing_document_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/billing_documents/8ad0855180f9da510180fbf80db40c79"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
BillingDocument billingDocumentResponse =
zuoraClient.billingDocuments().getBillingDocument(newInvoice.getId(),null,null);
System.out.println(billingDocumentResponse);
- lang: JavaScript
label: Node
source: >-
const billingDocResponse = await
zuoraClient.billingDocuments.getBillingDocument('8ad0887183f1cbe60183f5ccc9631fe8',{
expand:['items']
});
console.log(billingDocResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billingDocument'
example:
id: 8ad093f27f54fa8d017f6b191ff02543
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T14:16:31-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-03-08T11:54:43-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
description: comments
due_date: '2020-02-01'
document_date: '2020-02-01'
type: invoice
billing_document_number: INV00006606
amount_refunded: 0
state_transitions:
posted_at: '2022-03-08T11:54:43-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
remaining_balance: 225
amount_paid: 75
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/billing_documents:
get:
operationId: getBillingDocuments
summary: List billing documents
tags:
- Billing Documents
description: >-
Returns a dictionary with a data property that contains an array of
billing documents, starting after cursor. Each entry in the array is a
separate billing document object. If no more billing documents are
available, the resulting array will be empty. This request should never
return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/billing_documents?expand%5B%5D=items&filter%5B%5D=type.EQ%3Ainvoice"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
BillingDocumentListResponse billingDocumentListResponse =
zuoraClient.billingDocuments().getBillingDocuments(Collections.singletonList("type.EQ:invoice"),Collections.singletonList("items"),null);
System.out.println(billingDocumentListResponse);
- lang: JavaScript
label: Node
source: >-
const invoicesResponse = await
zuoraClient.billingDocuments.getBillingDocuments({
filter:['type.EQ:invoice'],
expand:['items']
});
console.log(invoicesResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billingDocumentListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: postBillingDocument
summary: Create a billing document
tags:
- Billing Documents
description: >-
Creates different types of billing document objects, including invoices,
credit memos, and debit memos.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/billingDocumentCreateRequest'
example:
account_id: 2c92c0f96abc17de016abd62bd0c5854
pay: false
description: comments
document_date: '2022-02-01'
type: invoice
post: true
items:
- amount: 300
booking_reference: bookingReference
document_item_date: '2022-02-10'
subscription_item_name: charge with tax amount 9
description: description
quantity: 2
service_end: '2022-02-10'
service_start: '2023-02-01'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `balance`, `description`, `state`, `tax`
</details>
- in: query
name: billing_document_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/billing_documents --header
'Authorization: Bearer 7676db88e1a84293a6298c8d44cc141c' --header
'Content-Type: application/json' --data '{
"account_id": "8ad08ccf806f42ed018090759555446b",
"pay": false,
"description": "new invoice",
"document_date": "2022-09-01",
"type": "invoice",
"post":true,
"items": [
{
"amount": 300,
"booking_reference": "PE2FGW",
"subscription_item_name": "a subscription item inclusive of tax",
"description": "A new invoice item",
"quantity": 2,
"service_end": "2023-09-01",
"service_start": "2022-09-01"
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
BillingDocumentItemCreateRequest invoiceItemRequest = new
BillingDocumentItemCreateRequest()
.amount(new BigDecimal(10.25))
.bookingReference("PE2FGW")
.subscriptionItemName("subscription item 1")
.description("a new invoice item")
.quantity(new BigDecimal(2))
.serviceEnd("2023-09-01")
.serviceStart("2022-09-01");
BillingDocumentCreateRequest invoiceRequest = new
BillingDocumentCreateRequest()
.accountId("8ad09c4b8262e38101826441928c1162")
.pay(false)
.description("new invoice")
.documentDate(todayDate)
.type(BillingDocumentCreateRequest.TypeEnum.INVOICE)
.post(false)
.items(Collections.singletonList(invoiceItemRequest));
BillingDocument newInvoice =
zuoraClient.billingDocuments().postBillingDocument(invoiceRequest);
- lang: JavaScript
label: Node
source: "\nconst billingDocItems = [{\n amount:100,\n booking_reference: 'PE2FGW',\t\n name: 'subscription item 1',\n description: 'a new invoice item',\n service_end: '2023-09-01',\n service_start: '2022-09-01',\n}];\n \nconst invoiceRequest = {\n account_id: '2c92c0f96abc17de016abd62bd0c5854',\n pay: false,\n description: 'new invoice',\n document_date: '2022-09-01',\n type: 'invoice',\n post: true,\n items: billingDocItems,\n};\n \nconst newInvoice = await zuoraClient.billingDocuments.postBillingDocument(invoiceRequest);\n "
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billingDocument'
example:
id: 8ad09b7d82d9662c0182daeaa9f4477e
billing_document_number: INV00006723
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-26T09:09:48-07:00'
updated_time: '2022-08-26T09:09:48-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state_transitions:
posted_at: '2022-08-26T09:09:48-07:00'
type: invoice
state: open
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
items:
next_page: null
data:
- type: invoice
amount: 10
created_by_id: 2c92c0946a6dffc0016a7faab604299b
discount_item: false
created_time: '2022-08-26T09:09:48-07:00'
custom_fields:
field__c: custom field value
document_item_date: '2022-08-26T09:09:48-07:00'
id: 8ad09b7d82d9662c0182daeaaa114781
sku: SKU-00011672
price_name: aaaaaa
quantity: 1
remaining_balance: 10
revenue_recognition_rule_name: Recognize upon invoicing
service_end: '2022-08-23'
service_start: '2022-08-23'
tax: 1.5
tax_inclusive: false
unit_amount: 0
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
total: 11.5
subtotal: 10
tax: 1.5
remaining_balance: 11.5
amount_paid: 0
paid: false
past_due: false
document_date: '2022-08-23'
due_date: '2022-09-22'
custom_fields:
field__c: custom field value
amount_refunded: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/billing_document_items:
get:
operationId: getBillingDocumentItems
summary: List billing document items
tags:
- Billing Document Items
description: List billing document items
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: billing_document_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `name`, `quantity`, `recognized_revenue_account`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_inclusive`, `unit_amount`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/billing_document_items?expand%5B%5D=subscription_item&filter%5B%5D=type.EQ%3Acredit_memo"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
BillingDocumentItemListResponse billingDocItemListResponse =
zuoraClient.billingDocuments().getBillingDocumentItems(Collections.singletonList("type.EQ:credit_memo"),
Collections.singletonList("subscription_item"), null);
System.out.println(billingDocItemListResponse);
- lang: JavaScript
label: Node
source: >-
const billingDocItemsResponse = await
zuoraClient.billingDocumentItems.getBillingDocumentItems({
filter:['type.EQ:credit_memo'],
expand: ['subscription_item'],
});
console.log(billingDocItemsResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billingDocumentItemListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/contacts/{contact_id}:
get:
operationId: getContact
summary: Retrieve a contact
tags:
- Contacts
description: Retrieves the contact with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: contact.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: contact_id
required: true
schema:
type: string
description: Contact Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/contacts/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Contact contactResponse =
zuoraClient.contact().getContact(contact.getId());
System.out.println(contactResponse);
- lang: JavaScript
label: Node
source: >-
const contactResponse = await
zuoraClient.contacts.getContact('8ad09bce844283060184475e7ee669f0');
console.log(contactResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateContact
summary: Update a contact
tags:
- Contacts
description: >-
Updates the specified contact by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/contactPatchRequest'
example:
first_name: James
last_name: Lawrence
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: contact.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: contact_id
required: true
schema:
type: string
description: Contact Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/contacts/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"address": {
"line1": "No.123, the 45th steet",
"postal_code": "98101",
"city": "Seattle",
"state": "Washington",
"country": "USA"
}
}'
- lang: Java
label: Java
source: >-
Contact oldContact =
zuoraClient.contact().getContact("8ad0991582aa848e0182ae9dad214dd0");
ContactPatchRequest contactPatchRequest = new ContactPatchRequest()
.address(new Address()
.country("USA")
.state("CA"));
Contact updatedContact =
zuoraClient.contact().updateContact(oldContact.getId(),contactPatchRequest);
- lang: JavaScript
label: Node
source: >-
const contactId = newContact.id;
const contactPatchRequest = {
address: {
country: 'USA',
state: 'CA'
}
};
const updatedContact = await
zuoraClient.contacts.updateContact(contactId, contactPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
example:
id: 8ad08e018262bc2b018265608a3e10e6
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:27:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: James
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteContact
summary: Delete a contact
tags:
- Contacts
description: Permanently deletes a contact. It cannot be undone.
parameters:
- in: path
name: contact_id
required: true
schema:
type: string
description: Contact Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/contacts/8ad08c0f7d0972ea017d0a705e8059ba'
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.contact().deleteContact(createdContact.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const contactDeleteResponse = await
zuoraClient.contacts.deleteContact('8ad09bce844283060184475e7ee669f0');
console.log(contactDeleteResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/contacts:
get:
operationId: getContacts
summary: List contacts
tags:
- Contacts
description: >-
Returns a dictionary with a data property that contains an array of
contacts, starting after the cursor, if used. Each entry in the array is
a separate contact object. If no more contacts are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: contact.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/contacts' --header
'Authorization: Bearer 08dacd3fe8b648f6861d5eb506d02a86'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
ListContactResponse contactListResponse =
zuoraClient.contact().getContacts(null,null,null,null);
System.out.println(contactListResponse);
- lang: JavaScript
label: Node
source: |-
const contactsResponse = await zuoraClient.contacts.getContacts({
filter: [
"first_name.SW:A"
]})
console.log(contactsResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/listContactResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createContact
summary: Create a contact
tags:
- Contacts
description: Creates a new contact object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/contactCreateRequest'
example:
account_id: 8ad085518262bc17018265525eab3696
first_name: Amy
last_name: Lawrence
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: USA
postal_code: '94065'
work_phone: (888) 976-9056
work_email: amy.lawrence@gmail.com
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: contact.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/contacts --header
'Authorization: Bearer d71a4363b94f42bca6e1453892818775'
--header 'Content-Type: application/json' --data '{
"account_id": "2c92c0f86cbe335a016cbece4a434ada",
"first_name": "Amy",
"last_name": "Lawrence"
}'
- lang: Java
label: Java
source: >-
ContactCreateRequest contactCreateRequest = new
ContactCreateRequest()
.accountId(account.getId())
.firstName("Amy")
.lastName("Lawrence");
Contact contact =
zuoraClient.contact().createContact(contactCreateRequest);
- lang: JavaScript
label: Node
source: >-
const contactCreateRequest = {
account_id: '2c92c0f86cbe335a016cbece4a434ada',
first_name: 'Amy',
last_name: 'Lawrence'
};
const newContact = await
zuoraClient.contacts.createContact(contactCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-03T13:23:21-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-03T13:23:21-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad085518262bc17018265525eab3696
address:
line1: 101 Redwood Shores Parkway
line2: Suite 1150
city: Redwood City
state: California
country: United States
postal_code: '94065'
first_name: Amy
last_name: Lawrence
work_email: amy.lawrence@gmail.com
work_phone: (888) 976-9056
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/contacts/{contact_id}/scrub:
post:
operationId: scrubContact
summary: Scrub a contact
tags:
- Contacts
description: Scrubs the sensitive data for the contact with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: contact.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: contact_id
required: true
schema:
type: string
description: Contact Id
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: scrub
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/contacts/8ad08c0f7d0972ea017d0a705e8059ba/scrub'
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.contact().scrubContact(createdContact.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const contactScrubResponse = await
zuoraClient.contacts.scrubContact('8ad09bce844283060184475e7ee669f0');
console.log(contactScrubResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods:
get:
operationId: getPaymentMethods
summary: List payment methods
tags:
- Payment Methods
description: >-
Returns a dictionary with a data property that contains an array of
payment methods, starting after the cursor, if used. Each entry in the
array is a separate payment method object. If no more payment methods
are available, the resulting array will be empty. This request should
never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createPaymentMethod
summary: Create a payment method
tags:
- Payment Methods
description: >-
Creates a new payment method object. See [Payment Pages 2.0
implementation
overview](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/1_Payment_Pages_2.0_Implementation_Overview)
to learn how to create payment methods through Hosted Payment Pages.
The `type` field in the request body schema of this operation enumerates the supported payment methods. Not all payment gateways support all these payment method types. Check <a href="https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods" target="
_blank">Supported payment methods</a> to check the supported payment methods for each gateway.
If you need to create payment methods outside the scope of this operaton, you have to use the [Create a payment method](https://developer.zuora.com/v1-api-reference/api/operation/POST_PaymentMethods/) operation of the v1 API instead of the Quickstart API.
We do not plan to add additional payment methods to the Quickstart API.
Any new payment methods will only be available through the v1 API and the Zuora client libraries.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodCreateRequest'
example:
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
is_default: false
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
state: California
country: United States
postal_code: '94065'
card:
card_number: '4111111111111111'
brand: visa
expiry_month: 12
expiry_year: 2025
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/payment_methods"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"type": "card",
"account_id": "2c92c0f86cbe335a016cbece4a434ada",
"is_default": true,
"card": {
"card_number": "41111111111",
"brand": "visa",
"expiry_month": 11,
"expiry_year": 2023
},
"billing_details": {
"name": "Amy"
}
}'
- lang: Java
label: Java
source: >-
Card card = new Card()
.cardNumber("41111111111")
.brand(BrandEnum.VISA)
.expiryMonth(new BigDecimal(11))
.expiryYear(new BigDecimal(2023));
PaymentMethodCreateRequest paymentMethodCreateRequest = new
PaymentMethodCreateRequest()
.type(TypeEnum.CARD)
.accountId(account.getId())
.isDefault(true)
.card(card)
.billingDetails(new BillingDetails().name("Amy"));
PaymentMethod newPaymentMethod =
zuoraClient.paymentMethods().createPaymentMethod(paymentMethodCreateRequest);
- lang: Node
label: Node
source: >-
const card = {
card_number: "41111111111",
brand: "visa",
expiry_month: 11,
expiry_year: 2023,
security_code: "123"
};
const paymentMethodCreateRequest = {
type: "card",
account_id: "2c92c8fb7d0f56c2017d11d88b7b2a5b",
is_default: true,
card: card,
billing_details: {
name: "Amy"
}
};
const newPaymentMethod = await
zuoraClient.paymentMethods.createPaymentMethod(paymentMethodCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethod'
example:
id: 8ad09b7d83165cd10183197e356c4ae3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T12:47:25-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T12:47:25-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods/{payment_method_id}:
get:
operationId: getPaymentMethodById
summary: Retrieve a payment method
tags:
- Payment Methods
description: Retrieves the payment method with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethod'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePaymentMethod
summary: Update a payment method
tags:
- Payment Methods
description: >-
Updates the specified payment method by setting the values of the
parameters passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodPatchRequest'
example:
billing_details:
address:
line1: 3333 Piedmont Rd NE
line2: Suite 1150
city: Atlanta
state: GA
country: USA
postal_code: '30305'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/payment_methods/8ad098317f6e9bec017f752fbe5a7141"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"card": {
"expiry_month": 11,
"expiry_year": 2024
}
}'
- lang: Java
label: Java
source: >-
PaymentMethod paymentMethod =
zuoraClient.paymentMethods().getPaymentMethodById("8ad098317f6e9bec017f752fbe5a7141");
CardUpdate card = new CardUpdate()
.expiryMonth(new BigDecimal(11))
.expiryYear(new BigDecimal(2024));
PaymentMethodPatchRequest paymentMethodPatchRequest = new
PaymentMethodPatchRequest()
.card(card);
PaymentMethod updatedPaymentMethod =
zuoraClient.paymentMethods().updatePaymentMethod(paymentMethod.getId(),
paymentMethodPatchRequest);
- lang: Node
label: Node
source: >-
const paymentMethod = await
zuoraClient.paymentMethods.getPaymentMethodById("8ad098317f6e9bec017f752fbe5a7141");
const card = {
expiry_month: 11,
expiry_year: 2024
};
const paymentMethodPatchRequest = {
card
};
const updatedPaymentMethod = await
zuoraClient.paymentMethods.updatePaymentMethod(paymentMethod.id,
paymentMethodPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethod'
example:
id: 8ad0823f83163bc5018318d62a2c0c40
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T10:48:31-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T09:43:52-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 3333 Piedmont Rd NE
line2: Suite 1150
city: Atlanta
country: United States
state: Georgia
postal_code: '30305'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deletePaymentMethod
summary: Delete a payment method
tags:
- Payment Methods
description: Permanently deletes a payment method. It cannot be undone.
parameters:
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods/{payment_method_id}/verify:
post:
operationId: verifyPaymentMethod
summary: Verify a payment method
tags:
- Payment Methods
description: >-
Sends an authorization request to the corresponding payment gateway to
verify the payment method. Supported payment methods are credit cards
and Paypal.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodVerificationRequest'
example:
currency: USD
security_code: '123'
payment_gateway: Test Gateway
gateway_options:
Comments: payment method verification
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: verify
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_methods/8ad08d2985aaee960185ac4da2264a91/verify
--header 'Authorization: Bearer 1c8f46f7f98b41e29c57f51ff9330ca5'
--header 'Content-Type: application/json' --data '{
"currency": "USD",
"security_code": "123",
"payment_gateway": "Test Gateway",
"gateway_options": {
"Comments": "payment method verification",
},
}'
- lang: Java
label: Java
source: >-
PaymentMethodVerificationRequest paymentMethodVerificationRequest =
new PaymentMethodVerificationRequest()
.currency("USD")
.securityCode("123")
.paymentGateWay("Test Gateway")
.gatewayOptions(new HashMap<String, String>() {{
put("Comments", "payment method verification");
}});
PaymentMethod verifiedPaymentMethod =
zuoraClient.paymentMethods().verifyPaymentMethod(newPaymentMethod.getId(),
paymentMethodVerificationRequest);
- lang: Node
label: Node
source: >-
const paymentMethodVerificationRequest = {
currency: "USD",
security_code: "123",
payment_gateway: "Test Gateway",
gateway_options: {
Comments: "payment method verification",
},
};
const verifiedPaymentMethod = await
zuoraClient.paymentMethods.verifyPaymentMethod(newPaymentMethod.id,
paymentMethodVerificationRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethod'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T08:52:24-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T08:52:24-07:00'
custom_fields:
field__c: custom field value
type: card
account_id: 2c92c0f86cbe335a016cbece4a434ada
billing_details:
name: Anabelle Padberg
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
country: United States
state: California
postal_code: '94065'
maximum_payment_attempts: 0
payment_retry_interval: 0
bank_identification_number: '411111'
card:
brand: visa
expiry_month: 12
expiry_year: 2025
last_4: '1111'
state: active
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods/{payment_method_id}/authorize:
post:
operationId: authorizePaymentMethod
summary: Create a payment authorization
tags:
- Payment Methods
description: >-
Verifies a payment method and block the amount of fund that will be used
for payment.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodAuthorizationRequest'
example:
amount: 200
gateway_order_id: 2c92c0f86a8dd422016a941ee0d82c7f
account_id: 8ad08ccf8437067601843a7af4e75ac8
required: true
parameters:
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: authorize
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/payment_methods/8ad098317f6e9bec017f752fbe5a7141/authorize"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"amount": "200",
"gateway_order_id": "2c92c0f86a8dd422016a941ee0d82c7f",
"account_id": "8ad08ccf8437067601843a7af4e75ac8",
}'
- lang: Java
label: Java
source: >-
PaymentMethodAuthorizationRequest paymentMethodAuthorizationRequest
= new PaymentMethodAuthorizationRequest()
.amount(new BigDecimal(10000))
.gatewayOrderId(2c92c0f86a8dd422016a941ee0d82c7f)
.accountId("8ad08ccf8437067601843a7af4e75ac8");
PaymentMethodAuthorizationResponse paymentMethodAuthorization =
zuoraClient.paymentMethods().authorizePaymentMethod(paymentMethod.getId(),
paymentMethodAuthorizationRequest);
- lang: Node
label: Node
source: >-
const paymentMethodAuthorizationRequest = {
"amount": "200",
"gateway_order_id": "2c92c0f86a8dd422016a941ee0d82c7f",
"account_id": "8ad08ccf8437067601843a7af4e75ac8",
};
const paymentMethodAuthorization = await
zuoraClient.paymentMethods.authorizePaymentMethod(paymentMethod.id,
paymentMethodAuthorizationRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodAuthorizationResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods/{payment_method_id}/void_authorization:
post:
operationId: voidAuthorizationPaymentMethod
summary: Cancel a payment authorization
tags:
- Payment Methods
description: Cancel or void the blocked fund from the specified payment method.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodVoidAuthorizationRequest'
example:
auth_transaction_id: '4832932.575712692'
gateway_order_id: 2c92c0f86a8dd422016a941ee0d82c7f
account_number: RC-00020831
required: true
parameters:
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: voidPaymentMethod
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/payment_methods/8ad098317f6e9bec017f752fbe5a7141/void_authorization"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"auth_transaction_id": "4832932.575712692",
"gateway_order_id": "2c92c0f86a8dd422016a941ee0d82c7f",
"account_number": "RC-00020831",
}'
- lang: Java
label: Java
source: >-
PaymentMethodVoidAuthorizationRequest
paymentMethodVoidAuthorizationRequest = new
PaymentMethodVoidAuthorizationRequest()
.authTransactionId("4832932.575712692")
.gatewayOrderId(2c92c0f86a8dd422016a941ee0d82c7f)
.accountNumber("RC-00020831");
PaymentMethodAuthorizationResponse paymentMethodVoidedAuthorization
=
zuoraClient.paymentMethods().voidAuthorizationPaymentMethod(paymentMethod.getId(),
paymentMethodVoidAuthorizationRequest);
- lang: Node
label: Node
source: >-
const paymentMethodVoidAuthorizationRequest = {
"auth_transaction_id": "4832932.575712692",
"gateway_order_id": "2c92c0f86a8dd422016a941ee0d82c7f",
"account_number": "RC-00020831",
};
const paymentMethodVoidedAuthorization = await
zuoraClient.paymentMethods.voidAuthorizationPaymentMethod(paymentMethod.id,
paymentMethodVoidAuthorizationRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentMethodAuthorizationResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_methods/{payment_method_id}/scrub:
post:
operationId: scrubPaymentMethod
summary: Scrub a payment method
tags:
- Payment Methods
description: >-
Scrubs sensitive data such as card number on the specified payment
method.
parameters:
- in: path
name: payment_method_id
required: true
schema:
type: string
description: Payment Method Id
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: scrub
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X POST
"https://rest.apisandbox.zuora.com/v2/payment_methods/8ad09fc282ce97650182d94dc21f27bf/scrub"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.paymentMethods().scrubPaymentMethod("8ad09fc282ce97650182d94dc21f27bf");
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const paymentMethodScrubResponse = await
zuoraClient.paymentMethods.scrubPaymentMethod('8ad09bce844283060184475e7ee669f0');
console.log(paymentMethodScrubResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}:
get:
operationId: getSubscriptionByKey
summary: Retrieve a subscription
tags:
- Subscriptions
description: >-
Retrieves the subscription with the given subscription key (number or
ID).
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08ccf82b04d020182b2ab71cc04d9?expand%5B%5D=subscription_plans'
--header 'Authorization: Bearer
35b5e974cd8447e69fd96adeefba9009' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Subscription subscriptionResponse =
zuoraClient.subscriptions().getSubscriptionByKey(createdSubscription.getId(),
null,Collections.singletonList("subscription_plans"), null);
System.out.println(subscriptionResponse);
- lang: JavaScript
label: Node
source: >-
const subscriptionResponse = await
zuoraClient.subscriptions.getSubscriptionByKey('8ad09c4b8442830201844adb05ac1bee',
{
expand: [
'subscription_plans'
]
});
console.log(subscriptionResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchSubscription
summary: Update a subscription
tags:
- Subscriptions
description: >-
Updates the specified subscription by setting the values of the
parameters passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPatchRequest'
example:
description: new subscription description
add_subscription_plans:
- subscription_plan:
plan_id: 8ad0824e7c980196017c9f3a60763eca
prices:
- price_id: 8ad084a67c9801a7017c9f3a6ba008d4
amount: 15
unique_token: SUB_PLAN_1530903
custom_fields:
field__c: custom field value
start_on:
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
update_subscription_plans:
- subscription_plan:
subscription_plan_id: 8ad0823f8292a2ce0182a31fe5ec220d
subscription_items:
- id: 8ad0823f8292a2ce0182a31fe5ec2210
quantity: 30
unit_amount: 239.99
start_date: '2022-08-15'
- id: 8ad0823f8292a2ce0182a31fe5ec2213
discount_percent: 20
start_on:
contract_effective: '2022-08-01'
service_activation: '2022-08-15'
customer_acceptance: '2022-08-30'
remove_subscription_plans:
- subscription_plan_id: 8ad0823f8292a2ce0182a31fe5ec2213
start_on:
contract_effective: '2022-06-01'
service_activation: '2022-06-01'
customer_acceptance: '2022-06-01'
custom_fields:
field__c: custom field value
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08ccf82afa5d70182afdb21f20017'
--header 'Authorization: Bearer
4e75a674142e4211911227da63d33d34' --header 'Content-Type:
application/json' --data '{
"description": "Updated subscription description",
"add_subscription_plans": [{
"subscription_plan":{
"plan_id": "8ad09bce8292b8480182a8ea00db35b3",
"prices":[{
"price_id": "8ad095b882aa84850182abbe78fd12f1"
}]
},
"start_on": {
"contract_effective": "2022-08-01",
"service_activation": "2022-08-01",
"customer_acceptance": "2022-08-01"
}
}]
}'
- lang: Java
label: Java
source: >2-
LocalDate date = LocalDate.of(2022,8,20);
String oldSubscriptionId = subscription.getId();
SubscriptionItemCreateRequest subscriptionItemCreateRequest = new
SubscriptionItemCreateRequest().priceId("8ad095b882aa84850182abbe78fd12f1");
SubscriptionPlanCreateRequest subscriptionPlanRequest = new
SubscriptionPlanCreateRequest()
.planId("8ad09bce8292b8480182a8ea00db35b3")
.prices(Collections.singletonList(subscriptionItemCreateRequest));
SubscriptionAddPlanPatchRequest addSubscriptionPlanRequest = new
SubscriptionAddPlanPatchRequest()
.subscriptionPlan(subscriptionPlanRequest)
.startOn((new StartOn()
.contractEffective(date)
.customerAcceptance(date)
.serviceActivation(date)));
SubscriptionPatchRequest updateRequest = new
SubscriptionPatchRequest()
.addSubscriptionPlans(Collections.singletonList(addSubscriptionPlanRequest));
Subscription updatedSubscription =
zuoraClient.subscriptions().patchSubscription(oldSubscriptionId,updateRequest);
- lang: JavaScript
label: Node
source: >-
const createdSubscription = await
zuoraClient.subscriptions.getSubscriptionByKey('8ad09c4b8442830201844adb05ac1bee');
const newDate = '2022-08-01';
const updatedSubscription = await
zuoraClient.subscriptions.patchSubscription(createdSubscription.id,
{
description: 'Add a new subscription plan',
add_subscription_plans: [
{
subscription_plan:{
plan_id: '8ad09bce8292b8480182a8ea00db35b3',
prices:[{
price_id: '8ad095b882aa84850182abbe78fd12f1',
}]
},
start_on: {
contract_effective: newDate,
service_activation: newDate,
customer_acceptance: newDate,
}
}]
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad09c4b819040ce018191b8433c4b5a
custom_fields:
field__c: custom field value
subscription_number: A-S00013199
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: evergreen
current_term:
interval_count: 0
start_date: '2022-07-01'
type: evergreen
start_date: '2022-06-01'
description: Update Custom Fields
contract_effective: '2022-06-01'
service_activation: '2022-06-01'
customer_acceptance: '2022-06-01'
invoice_separately: false
invoice_owner_account_id: 2c92c0f86ab120d4016ab3799e955147
order_number: O-00020539
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions:
get:
operationId: getSubscriptions
summary: List subscriptions
tags:
- Subscriptions
description: >-
Returns a dictionary with a data property that contains an array of
subscriptions, starting after the cursor, if used. Each entry in the
array is a separate subscription object. If no more subscriptions are
available, the resulting array will be empty. This request should never
return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/subscriptions' --header
'Authorization: Bearer d8a7f4d2a5ef4c3eba8618cf99593e26'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
SubscriptionListResponse subscriptionListResponse =
zuoraClient.subscriptions().getSubscriptions(null,Collections.singletonList("subscription_plans"),
Collections.singletonList("state.EQ:active"));
System.out.println(subscriptionListResponse);
- lang: JavaScript
label: Node
source: >-
const subscriptionListResponse = await
zuoraClient.subscriptions.getSubscriptions({
filter: [
'state.EQ:active'
],
expand: [
'subscription_plans'
]},
);
console.log(subscriptionListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createSubscription
summary: Create a subscription
tags:
- Subscriptions
description: Creates a new subscription.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionCreateRequest'
example:
account_id: RC-00000011
auto_renew: true
initial_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
start_on:
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
description: Create Subscription
invoice_separately: false
custom_fields:
field__c: custom field value
subscription_plans:
- plan_id: 8ad0824e7c980196017c9f3a60763eca
prices:
- price_id: 8ad084a67c9801a7017c9f3a6ba008d4
amount: 15
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/subscriptions' --header
'Authorization: Bearer a2f068a99a4d4a94ab5fe229c14d3220'
--header 'Content-Type: application/json' --data '{
"account_id": "8ad09b7d8292b85d0182a4d6f875225a",
"subscription_plans": [{
"plan_id": "8ad09bce82aa84840182afab5e7b04fb",
"prices": [{
"price_id": "8ad0887182afa5d00182b017730c5fcb",
"quantity": 20
}]
}],
"processing_options":{
"collection_method": "create_invoice",
"document_date": "2022-10-01"
},
"start_on":{
"contract_effective": "2022-10-01",
"customer_acceptance": "2022-10-01",
"service_activation": "2022-10-01"
}
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
SubscriptionItemCreateRequest subscriptionItemCreateRequest = new
SubscriptionItemCreateRequest().priceId(newPrice.getId());
SubscriptionCreateRequest subscriptionCreateRequest = new
SubscriptionCreateRequest()
.accountId(account.getId())
.subscriptionPlans(Collections.singletonList(new SubscriptionPlanCreateRequest()
.planId(newPlan.getId())
.prices(Collections.singletonList(subscriptionItemCreateRequest))))
.processingOptions(new ProcessingOptions()
.collectionMethod(CollectionMethodEnum.CREATE_INVOICE)
.documentDate(todayDate.plusMonths(2)))
.startOn(new StartOn()
.contractEffective(todayDate)
.customerAcceptance(todayDate)
.serviceActivation(todayDate));
Subscription subscription =
zuoraClient.subscriptions().createSubscription(subscriptionCreateRequest);
- lang: JavaScript
label: Node
source: >-
const account = await
zuoraClient.accounts.getAccount("8ad0950c844283030184471f07e834c7");
const date = new Date();
const todayDate = date.toISOString().split('T')[0];
const planId = '8ad0877b843cb3df01843fc6351b2128';
const subscriptionCreateRequest = {
account_id: account.id,
subscription_plans: [
{
plan_id: planId,
}
],
processing_options:{
collection_method: 'create_invoice',
document_date: todayDate,
},
start_on:{
contract_effective: todayDate,
customer_acceptance: todayDate,
service_activation: todayDate
}
};
const newSubscription = await
zuoraClient.subscriptions.createSubscription(subscriptionCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/pause:
post:
operationId: pauseSubscription
summary: Pause a subscription
tags:
- Subscriptions
description: Pauses a subscription.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pauseSubscriptionRequest'
example:
pause_date: '2022-06-15'
pause_interval: month
pause_interval_count: 1
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: pause
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/pause'
--header 'Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3'
--header 'Content-Type: application/json' --data '{
"pause_date": "2022-10-01",
"pause_at":"invoice_period_end",
"resume_behavior": {
"resume_date": "2023-01-01",
}
}'
- lang: Java
label: Java
source: >2-
String subscriptionId = subscription.getId();
PauseSubscriptionRequest pauseRequest = new
PauseSubscriptionRequest()
.pauseDate("2022-10-01")
.pauseAt(PauseSubscriptionRequest.PauseAtEnum.INVOICE_PERIOD_END)
.resumeBehavior(new ResumeSubscriptionRequest().resumeDate("2023-01-01"));
Subscription pausedSubscription =
zuoraClient.subscriptions().pauseSubscription(subscriptionId,
pauseRequest);
- lang: JavaScript
label: Node
source: >-
const pausedSubscription = await
zuoraClient.subscriptions.pauseSubscription('8ad095b8844282ff0184528d63f3242f',{
pause_date: '2022-12-01',
pause_interval_count: '1',
pause_interval: 'week',
resume_behavior: {
extend_term: 'true',
},
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad09c4b8258af4901825f043f5a40f3
custom_fields:
field__c: custom field value
subscription_number: A-S00013324
state: paused
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/resume:
post:
operationId: resumeSubscription
summary: Resume a subscription
tags:
- Subscriptions
description: Resumes a subscription.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/resumeSubscriptionRequest'
example:
resume_date: '2022-09-01'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: resume
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/resume'
--header 'Authorization: Bearer
6d151216ef504f65b8ff6e9e9e8356d3' --header 'Content-Type:
application/json' --data '{
"extend_term": true,
"resume_date": "2023-01-01"
}'
- lang: Java
label: Java
source: >2-
String pausedSubscriptionId = suspendedSubscription.getId();
ResumeSubscriptionRequest resumeRequest = new
ResumeSubscriptionRequest()
.extendTerm(true)
.resumeDate("2023-01-01");
Subscription resumedSubscription =
zuoraClient.subscriptions().resumeSubscription(pausedSubscriptionId,
resumeRequest);
- lang: JavaScript
label: Node
source: >-
const resumedSubscription = await
zuoraClient.subscriptions.resumeSubscription('8ad08ccf80efe77c0180f1f5f80d39c9',{
extend_term: true,
resume_date: '2022-12-01',
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad09b7d8322303e01832308552f417b
custom_fields:
field__c: custom field value
subscription_number: A-S00013333
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
type: termed
interval_count: 12
interval: month
current_term:
type: termed
start_date: '2022-05-01'
end_date: '2023-05-01'
interval_count: 12
interval: month
renewal_term:
type: evergreen
start_date: '2022-05-01'
end_date: '2023-05-01'
description: Test subscription description
contract_effective: '2022-05-01'
service_activation: '2022-05-01'
customer_acceptance: '2022-05-01'
invoice_separately: true
order_number: O-00021146
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/cancel:
post:
operationId: cancelSubscription
summary: Cancel a subscription
tags:
- Subscriptions
description: Cancels a subscription.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/cancelSubscriptionRequest'
example:
cancel_date: '2022-10-01'
write_off: true
write_off_behavior:
recognized_revenue_accounting_code: Subscription Revenue
deferred_revenue_accounting_code: Subscription Revenue
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/cancel'
--header 'Authorization: Bearer
6d151216ef504f65b8ff6e9e9e8356d3' --header 'Content-Type:
application/json' --data '{
"cancel_date": "2022-09-01",
"cancel_at": "invoice_period_end"
}'
- lang: Java
label: Java
source: >2-
String subscriptionId = subscription.getId();
CancelSubscriptionRequest cancelRequest = new
CancelSubscriptionRequest()
.cancelDate("2022-09-01")
.cancelAt(CancelAtEnum.INVOICE_PERIOD_END);
Subscription canceledSubscription =
zuoraClient.subscriptions().cancelSubscription(subscriptionId,cancelRequest);
- lang: JavaScript
label: Node
source: >-
const canceledSubscription = await
zuoraClient.subscriptions.cancelSubscription('8ad0855183f1cbdd0183f895456b0c43',
{
cancel_date: '2023-01-01'
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionCancelResponse'
example:
id: 8ad08dc9878f3dd6018790c8998f05bf
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-17T12:54:38-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-17T12:54:38-07:00'
custom_fields:
cancel_Reason_Code__c: Customer Initiated
subscription_number: A-S00014014
state: canceled
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0823f8455bb400184633077e63aaf
auto_renew: true
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: month
current_term:
type: termed
start_date: '2022-11-04'
end_date: '2022-10-01'
interval_count: 1
interval: month
renewal_term:
type: termed
interval_count: 1
interval: month
start_date: '2022-11-04'
end_date: '2022-10-01'
description: test subscription
contract_effective: '2022-11-04'
service_activation: '2022-11-04'
customer_acceptance: '2022-11-04'
invoice_separately: false
version: 2
order_number: O-00023516
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/keep:
post:
operationId: uncancelSubscription
summary: Uncancel a subscription
tags:
- Subscriptions
description: Uncancel a cancelled subscription.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPatchRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
deprecated: true
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/keep'
--header 'Authorization: Bearer
6d151216ef504f65b8ff6e9e9e8356d3' --header 'Content-Type:
application/json' --data '{
"description": "Uncancelling a cancelled subscription"
}'
- lang: Java
label: Java
source: >2-
String canceledSubscriptionId = canceledSubscription.getId();
SubscriptionPatchRequest uncancelRequest = new
SubscriptionPatchRequest()
.description("Uncancelling a cancelled subscription");
Subscription uncanceledSubscription =
zuoraClient.subscriptions().uncancelSubscription(canceledSubscriptionId,uncancelRequest);
- lang: JavaScript
label: Node
source: >-
const uncanceledSubscription = await
zuoraClient.subscriptions.uncancelSubscription(canceledSubscription.Id,{
description: "Uncancelling a cancelled subscription",
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_number: A-S0001332401234
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: month
type: termed
current_term:
interval_count: 1
interval: month
start_date: '2022-07-01'
type: termed
end_date: '2022-08-01'
start_date: '2022-07-01'
end_date: '2022-08-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-07-01'
customer_acceptance: '2022-07-01'
invoice_separately: false
order_number: O-00020812
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/activate:
post:
operationId: activateSubscription
summary: Activate a subscription
tags:
- Subscriptions
description: >-
A subscription must be active before you can bill your subscribers.
Activating a subscription requires entering at least one of the
following dates: `contract_effective`, `service_activation`, and
`customer_acceptance`. See [Billing Trigger
Dates](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/WA_Dates_in_Zuora/B_Subscription_and_Amendment_Dates#Billing_Trigger_Dates)
for more information.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionActivateRequest'
example:
service_activation: '2022-08-01'
customer_acceptance: '2022-08-01'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: activate
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'https://rest.sandbox.na.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/activate'
--header 'Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3'
--header 'Content-Type: application/json' --data '{
"contract_effective": "2022-10-01"
}'
- lang: Java
label: Java
source: >2-
LocalDate date = LocalDate.of(2022,10,01);
String subscriptionId = subscription.getId();
SubscriptionActivateRequest activateSubscriptionRequest = new
SubscriptionActivateRequest()
.contractEffective(date);
Subscription activatedSubscription =
zuoraClient.subscriptions().activateSubscription(subscriptionId,
activateSubscriptionRequest);
- lang: JavaScript
label: Node
source: >-
const date = new Date();
const todayDate = date.toISOString().split('T')[0];
const activatedSubscription = await
zuoraClient.subscriptions.activateSubscription('8ad0855180f9da510180fbf80cea0c4a',{
contract_effective: todayDate,
customer_acceptance: todayDate,
service_activation: todayDate,
});
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscription'
example:
id: 8ad09b7d8258af4401825f733e6c43ae
custom_fields:
field__c: custom field value
subscription_number: A-S00013332
state: active
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
invoice_owner_account_id: 2c92c0f86a8dd422016a9e7a70116b0d
auto_renew: true
latest_version: true
initial_term:
interval_count: 1
interval: year
type: termed
current_term:
interval_count: 1
interval: year
start_date: '2022-07-01'
type: termed
end_date: '2023-07-01'
start_date: '2022-07-01'
end_date: '2023-07-01'
description: Create Subscription
contract_effective: '2022-07-01'
service_activation: '2022-08-01'
customer_acceptance: '2022-08-01'
invoice_separately: false
order_number: O-00020843
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/preview:
post:
operationId: previewSubscription
summary: Preview a subscription
tags:
- Subscriptions
description: >-
You can preview the billing document metrics or the order delta metrics
across a specified time frame.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPreviewRequest'
example:
account_id: 8ad09b7d8292b85d0182a4d6f875225a
subscription_plans:
- plan_id: 8ad09bce82aa84840182afab5e7b04fb
metrics:
- billing_documents
end_date: '2022-11-05'
required: true
parameters:
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: preview
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl --request POST
--url 'https://rest.apisandbox.zuora.com/v2/subscriptions/preview'
--header 'Authorization: Bearer 2e4e1763af7d4cf5aaca1b519dfa3200'
--header 'Content-Type: application/json'
--data '{
"account_id": "8ad09b7d8292b85d0182a4d6f875225a",
"subscription_plans": [
{
"plan_id": "8ad09bce82aa84840182afab5e7b04fb"
}
],
"end_date": "2022-11-30",
"metrics": ["billing_documents"]
}'
- lang: Java
label: Java
source: >-
LocalDate date = LocalDate.of(2022,11,30);
String planId = newPlan.getId();
String accountId = newAccount.getId();
SubscriptionPreviewRequest previewRequest = new
SubscriptionPreviewRequest()
.metrics(Collections.singletonList(SubscriptionPreviewRequest.MetricsEnum.BILLING_DOCUMENTS))
.endDate(date)
.accountId(accountId)
.subscriptionPlans(Collections.singletonList(new SubscriptionPlanCreateRequest()
.planId(planId)));
Map<String, Object> subscription =
zuoraClient.subscriptions().previewSubscription(previewRequest);
- lang: JavaScript
label: Node
source: >-
const previewRequest = {
account_id: '8ad09b7d8292b85d0182a4d6f875225a',
subscription_plans: [
{
plan_id: '8ad09bce82aa84840182afab5e7b04fb'
}
],
end_date: "2022-11-30",
metrics: ["billing_documents"]
}
const previewSubscription = await
zuoraClient.subscriptions.previewSubscription(previewRequest);
console.log(previewSubscription);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPreviewResponse'
example:
billing_documents:
- type: invoice
subtotal: 200
target_date: '2023-11-05'
tax: 0
total: 200
billing_document_items:
- price_id: 8ad0887182afa5d00182b017730c5fcb
processing_type: subscription_item
product_name: Gold Membership
quantity: 1
service_start_date: '2022-10-24'
service_end_date: '2022-10-30'
subscription_item_description: Price description
subscription_item_name: Test price name
subtotal: 100
tax: 0
total: 100
unit_of_measure: Bottle
- price_id: 8ad0887182afa5d00182b017730c5fcb
processing_type: subscription_item
product_name: Gold Membership
quantity: 1
service_start_date: '2022-10-31'
service_end_date: '2022-11-06'
subscription_item_description: Price description
subscription_item_name: Test price name
subtotal: 100
tax: 0
total: 100
unit_of_measure: Bottle
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/preview:
post:
operationId: previewExistingSubscription
summary: Preview an existing subscription
tags:
- Subscriptions
description: >-
You can preview the billing document metrics or the order delta metrics
across a specified time frame.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPreviewExistingRequest'
example:
account_id: 8ad08d29857fc0ec0185829faf0507d7
description: lorem ipsum dolor sit amet
number_of_periods: 2
term_end: true
end_date: '2023-08-20'
custom_fields:
TestSubscriptionRequired__c: abc
add_subscription_plans:
- subscription_plan:
plan_id: 8ad09fc2843cc2fb01843f449ab45485
prices:
- price_id: 8ad095dd843cc2f601843fa041862032
description: abc
quantity: 25
discount_percent: 15
recurring:
recurring_on: account_cycle_date
update_subscription_plans:
- subscription_plan:
subscription_plan_id: 8ad08dc985c965370185cb0af2f77fb5
subscription_items:
- id: 8ad08dc985c965370185cb0af2f77fb6
quantity: 1
unit_amount: 10
start_date: '2023-01-30'
start_on:
contract_effective: '2023-01-30'
service_activation: '2023-01-30'
customer_acceptance: '2023-01-30'
metrics:
- billing_documents
- delta_metrics
required: true
parameters:
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/subscriptions/A-S00013732/preview
--header 'Authorization: Bearer 4a6cebacd36f4c8c9c20c4986ba3f78c'
--header 'Content-Type: application/json' --header 'x-donut-auth:
Bearer 4a6cebacd36f4c8c9c20c4986ba3f78c' --data '{
"account_id": "8ad08d29857fc0ec0185829faf0507d7",
"description": "lorem ipsum dolor sit amet",
"number_of_periods": 1,
"term_end": false,
"end_date": "2023-08-20",
"custom_fields": {
"TestSubscriptionRequired__c": "abc"
},
"add_subscription_plans": [
{
"subscription_plan": {
"plan_id": "8ad09fc2843cc2fb01843f449ab45485",
"prices": [
{
"price_id": "8ad095dd843cc2f601843fa041862032",
"description": "abc",
"quantity": 25,
"discount_percent": 15,
"recurring": {
"recurring_on": "account_cycle_date"
}
}
]
}
}
],
"update_subscription_plans": [
{
"subscription_plan": {
"subscription_plan_id": "8ad08dc985c965370185cb0af2f77fb5",
"subscription_items": [
{
"id": "8ad08dc985c965370185cb0af2f77fb6",
"quantity": 1,
"unit_amount": 10,
"start_date": "2023-01-30"
}
]
},
"start_on": {
"contract_effective": "2023-01-30",
"service_activation": "2023-01-30",
"customer_acceptance": "2023-01-30"
}
}
],
"metrics": [
"billing_documents",
"delta_metrics"
]
}'
- lang: Java
label: Java
source: >-
String subscriptionId = "8a8aa3bc90c4f1690190e7c25abd3d24";
String account_number = "A00000019";
LocalDate endDate = LocalDate.of(2025,1,1);
String description = "Preview your subscription";
SubscriptionItemPatchRequest newItem = new SubscriptionItemPatchRequest()
.subscriptionItemNumber("C-00000020")
.endDate(endDate);
SubscriptionUpdatePlanPatchRequest subscriptionUpdatePlanPatchRequest = new SubscriptionUpdatePlanPatchRequest()
.subscriptionPlan(new SubscriptionPlanPatchRequest()
.subscriptionPlanId("8a8aa3bc90c4f1690190e7c25b663d2a")
.subscriptionItems(new ArrayList<>((Arrays.asList(newItem)))));
SubscriptionPreviewExistingRequest subscriptionPreviewExistingRequest = new SubscriptionPreviewExistingRequest()
.accountId(account_number)
.description(description)
.updateSubscriptionPlans(new ArrayList<>(Arrays.asList(subscriptionUpdatePlanPatchRequest)))
.metrics(new ArrayList<>(Arrays.asList(
SubscriptionPreviewExistingRequest.MetricsEnum.BILLING_DOCUMENTS,
SubscriptionPreviewExistingRequest.MetricsEnum.DELTA_METRICS
)));
SubscriptionPreviewResponse subscription = zuoraClient.subscriptions().previewExistingSubscription(subscriptionId,subscriptionPreviewExistingRequest);
System.out.print(subscription);
- lang: JavaScript
label: Node
source: >-
const previewRequest = {
account_id: "8ad08d29857fc0ec0185829faf0507d7",
description: "lorem ipsum dolor sit amet",
number_of_periods: 2,
term_end: true,
end_date: "2023-08-20",
custom_fields: {
TestSubscriptionRequired__c: "abc"
},
add_subscription_plans: [
{
subscription_plan: {
plan_id: "8ad09fc2843cc2fb01843f449ab45485",
prices: [
{
price_id: "8ad095dd843cc2f601843fa041862032",
description: "abc",
quantity: 25,
discount_percent: 15,
recurring: {
recurring_on: "account_cycle_date"
}
}
]
}
}
],
update_subscription_plans: [
{
subscription_plan: {
subscription_plan_id: "8ad08dc985c965370185cb0af2f77fb5",
subscription_items: [
{
id: "8ad08dc985c965370185cb0af2f77fb6",
quantity: 1,
unit_amount: 10,
start_date: "2023-01-30"
}
]
},
start_on: {
contract_effective: "2023-01-30",
service_activation: "2023-01-30",
customer_acceptance: "2023-01-30"
},
}
],
metrics: [
"billing_documents",
"delta_metrics"
]
},
const previewSubscription = await
zuoraClient.subscriptions.previewExistingSubscription(previewRequest);
console.log(previewSubscription);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPreviewResponse'
example:
actions:
- action_id: 8ad08dc986023f76018603e36b4265c3
subscription_number: A-S00013732
action: update_subscription_plan
sequence: 0
subscription_items:
- subscription_item_id: 8ad08dc986023f76018603e36ccc65e1
price_id: 8ad095dd843cc2f601843fa041862032
start_date: '2023-01-30'
end_date: '2024-01-01'
tcb:
gross_amount: 2766.129032258
net_amount: 2766.129032258
currency: USD
mrr:
gross_amount: 250
net_amount: 250
currency: USD
- subscription_item_id: 8ad08dc986023f76018603e36ccc65e2
price_id: 8ad09bce843cc2ed01843faa4b0279db
start_date: '2023-01-30'
end_date: '2023-01-31'
tcb:
gross_amount: 1
net_amount: 1
currency: USD
- action_id: 8ad08dc986023f76018603e36b4265c4
subscription_number: A-S00013732
action: update_subscription_plan
sequence: 1
subscription_items:
- subscription_item_id: 8ad08dc986023f76018603e36c5465d4
price_id: 8ad0991583ac6e130183ae83026637a7
start_date: '2023-01-30'
end_date: '2024-01-01'
tcb:
gross_amount: -22129.032258065
net_amount: -22129.032258065
currency: USD
mrr:
gross_amount: -2000
net_amount: -2000
currency: USD
- subscription_item_id: 8ad08dc986023f76018603e36c9a65d8
price_id: 8ad0991583ac6e130183ae83026637a7
start_date: '2023-01-30'
end_date: '2024-01-01'
tcb:
gross_amount: 110.64516129
net_amount: 110.64516129
currency: USD
mrr:
gross_amount: 10
net_amount: 10
currency: USD
billing_documents:
- type: invoice
subtotal: 537.78
target_date: '2023-03-01'
tax: 0
total: 537.78
billing_document_items:
- price_id: 8ad095dd843cc2f601843fa041862032
processing_type: subscription_item
product_name: Music Stream Plus
quantity: 25
service_start_date: '2023-01-30'
service_end_date: '2023-01-31'
subscription_item_description: abc
subscription_item_name: Recurring Monthly Plan
subtotal: 16.13
tax: 0
total: 16.13
unit_of_measure: License
- price_id: 8ad095dd843cc2f601843fa041862032
processing_type: subscription_item
product_name: Music Stream Plus
quantity: 25
service_start_date: '2023-02-01'
service_end_date: '2023-02-28'
subscription_item_description: abc
subscription_item_name: Recurring Monthly Plan
subtotal: 250
tax: 0
total: 250
unit_of_measure: License
- type: credit_memo
subtotal: 129.03
target_date: '2023-03-01'
tax: 0
total: 129.03
billing_document_items:
- price_id: 8ad0991583ac6e130183ae83026637a7
processing_type: subscription_item
product_name: Sub Testing
quantity: 10
service_start_date: '2023-01-30'
service_end_date: '2023-01-31'
subscription_item_name: Recurring - Unit Amount Upgrade
subscription_item_number: C-00049360
subtotal: 129.03
tax: 0
total: 129.03
unit_of_measure: Each
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscriptions/{subscription_id}/versions:
get:
operationId: getSubscriptionByVersion
summary: List all versions of a subscription
tags:
- Subscriptions
description: Lists all versions of the specified subscription.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_version.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`, `price`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: invoice_owner_account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: prepaid_balance.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`
</details>
- in: query
name: prepaid_balances.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`validity_periods`
</details>
- in: query
name: validity_period.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity`
</details>
- in: query
name: transactions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`transaction_date`, `type`, `quantity`
</details>
- in: query
name: actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_id
required: true
schema:
type: string
description: >-
Identifier for the subscription, either `subscription_number` or
`subscription_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: listVersions
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/subscriptions/A-S00013892/versions'
--header 'Authorization: Bearer
35b5e974cd8447e69fd96adeefba9009' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Subscription subscriptionVersionResponse =
zuoraClient.subscriptions().getSubscriptionByVersion(createdSubscription.getSubscriptionNumber(),
null,Collections.singletonList("actions"), null);
System.out.println(subscriptionVersionResponse);
- lang: JavaScript
label: Node
source: >-
const subscriptionVersionResponse = await
zuoraClient.subscriptions.getSubscriptionByVersion('A-S00013892', {
expand: [
'actions'
]
});
console.log(subscriptionVersionResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionVersionListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-14T11:24:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-14T11:24:50-07:00'
custom_fields:
BusinessUnit__c: unit 1
testDate__c: '2023-01-01'
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
XiOEndUser__c: test user
subscription_number: A-S0001389201234
state: active
version: 15
account_id: 8ad08d29857fc0ec0185829faf0507d7
invoice_owner_account_id: 8ad08d2986df2c8b0186e0e6080c472f
auto_renew: false
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-03-07'
end_date: '2024-03-07'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-03-07'
end_date: '2024-03-07'
description: ''
contract_effective: '2023-03-07'
service_activation: '2023-03-07'
customer_acceptance: '2023-03-07'
invoice_separately: false
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-14T11:24:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-14T11:24:50-07:00'
custom_fields:
BusinessUnit__c: unit 1
testDate__c: '2023-01-01'
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
XiOEndUser__c: test user
subscription_number: A-S0001389201234
state: active
version: 15
account_id: 8ad08d29857fc0ec0185829faf0507d7
invoice_owner_account_id: 8ad08d2986df2c8b0186e0e6080c472f
auto_renew: false
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-03-07'
end_date: '2024-03-07'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-03-07'
end_date: '2024-03-07'
description: ''
contract_effective: '2023-03-07'
service_activation: '2023-03-07'
customer_acceptance: '2023-03-07'
invoice_separately: false
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-14T11:24:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-14T11:24:50-07:00'
custom_fields:
BusinessUnit__c: unit 1
testDate__c: '2023-01-01'
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
XiOEndUser__c: test user
subscription_number: A-S0001389201234
state: active
version: 15
account_id: 8ad08d29857fc0ec0185829faf0507d7
invoice_owner_account_id: 8ad08d2986df2c8b0186e0e6080c472f
auto_renew: false
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-03-07'
end_date: '2024-03-07'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-03-07'
end_date: '2024-03-07'
description: ''
contract_effective: '2023-03-07'
service_activation: '2023-03-07'
customer_acceptance: '2023-03-07'
invoice_separately: false
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-14T11:24:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-14T11:24:50-07:00'
custom_fields:
BusinessUnit__c: unit 1
testDate__c: '2023-01-01'
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
XiOEndUser__c: test user
subscription_number: A-S0001389201234
state: active
version: 15
account_id: 8ad08d29857fc0ec0185829faf0507d7
invoice_owner_account_id: 8ad08d2986df2c8b0186e0e6080c472f
auto_renew: false
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-03-07'
end_date: '2024-03-07'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-03-07'
end_date: '2024-03-07'
description: ''
contract_effective: '2023-03-07'
service_activation: '2023-03-07'
customer_acceptance: '2023-03-07'
invoice_separately: false
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-14T11:24:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-14T11:24:50-07:00'
custom_fields:
BusinessUnit__c: unit 1
testDate__c: '2023-01-01'
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
XiOEndUser__c: test user
subscription_number: A-S0001389201234
state: active
version: 15
account_id: 8ad08d29857fc0ec0185829faf0507d7
invoice_owner_account_id: 8ad08d2986df2c8b0186e0e6080c472f
auto_renew: false
latest_version: true
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-03-07'
end_date: '2024-03-07'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-03-07'
end_date: '2024-03-07'
description: ''
contract_effective: '2023-03-07'
service_activation: '2023-03-07'
customer_acceptance: '2023-03-07'
invoice_separately: false
bill_to_id: null
payment_terms: null
billing_document_settings:
sequence_set_id: null
template_id: null
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/workflows/{workflow_id}/run:
post:
operationId: runWorkflow
summary: Run a workflow
tags:
- Workflows
description: >-
Run a specified workflow. In the request body, you can include
parameters that you want to pass to the workflow. For the parameters to
be recognized and picked up by tasks in the workflow, you need to define
the parameters first.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/runWorkflowRequest'
example:
input_parameters:
days: '12'
required: true
parameters:
- in: path
name: workflow_id
required: true
schema:
type: integer
description: Workflow Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X POST
"https://rest.sandbox.na.zuora.com/v2/workflows/132/run"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"input_parameters": {
"payment_id": "4028905f5a87c0ff015a889ddfb800c0"
}
}'
- lang: Java
label: Java
source: >-
Integer workflowId = workflow.getId();
Map<String, String> inputParam = new HashMap<>();
inputParam.put("paymentId","4028905f5a87c0ff015a889ddfb800c0");
RunWorkflowRequest runWorkflowRequest = new
RunWorkflowRequest().inputParameters(inputParam);
WorkflowRun workflowRun = zuoraClient.workflows().runWorkflow(132,
runWorkflowRequest);
- lang: JavaScript
label: Node
source: >2-
const runWorkflowRequest = {
input_parameters: {
payment_id: '4028905f5a87c0ff015a889ddfb800c0',
},
};
const workflowRun = await zuoraClient.workflows.runWorkflow(132,
runWorkflowRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/workflowRun'
example:
id: 48848
name: WF-36176-00000010
original_workflow_id: 36176
state: queued
created_time: '2022-08-04T16:09:18.000Z'
updated_time: 2022-08-04 16:09:18 UTC
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/products/{product_id}:
get:
operationId: getProduct
summary: Retrieve a product
tags:
- Products
description: Retrieves the product with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: product_id
required: true
schema:
type: string
description: Product Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/product'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateProduct
summary: Update a product
tags:
- Products
description: >-
Updates the specific product by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/productPatchRequest'
example:
description: Update end_date
end_date: '2035-07-01'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: product_id
required: true
schema:
type: string
description: Product Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/products/{product_id}"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "New Gold",
"description": "New Gold Product",
"start_date": "2022-01-01",
"end_date": "2032-01-01"
}'
- lang: Java
label: Java
source: >-
Product newProduct =
zuoraClient.products().createProduct(productRequest);
LocalDate newStartDate = LocalDate.of(2022, 1, 1);
LocalDate newEndDate = LocalDate.of(2032, 1, 1);
ProductPatchRequest updateProductRequest = new ProductPatchRequest()
.name("New Gold")
.startDate(newStartDate)
.endDate(newEndDate)
.description("New Gold Product");
Product updatedProduct =
zuoraClient.products().updateProduct(newProduct.getId(),
updateProductRequest);
- lang: JavaScript
label: Node
source: >-
const updateProductReq = {
name: "New Gold",
description: "New Gold Product",
start_date: "2022-01-01",
end_date: "2032-01-01",
};
const updatedProduct = await
zuoraClient.products.updateProduct(newProduct.Id, updateProductReq);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/product'
example:
id: 8ad09fc28258af4a01825f2cd30871cd
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:39:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2035-07-01'
name: Software service
type: base
description: Update end_date
sku: SKU-00011719
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteProduct
summary: Delete a product
tags:
- Products
description: Permanently deletes a product. It cannot be undone.
parameters:
- in: path
name: product_id
required: true
schema:
type: string
description: Product Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/products:
get:
operationId: getProducts
summary: List products
tags:
- Products
description: >-
Returns a dictionary with a data property that contains an array of
products, starting after the cursor, if used. Each entry in the array is
a separate product object. If no more products are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 10
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/productListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createProduct
summary: Create a product
tags:
- Products
description: Creates a new product object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/productCreateRequest'
example:
name: Software service
description: Software service - basic edition
start_date: '2022-07-01'
end_date: '2032-07-01'
type: base
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/products"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "Gold",
"sku": "SKU3677",
"description": "Gold Product",
"start_date": "2022-04-01",
"end_date": "2032-04-01"
}'
- lang: Java
label: Java
source: >-
LocalDate startDate = LocalDate.of(2022, 4, 1);
LocalDate endDate = LocalDate.of(2032, 4, 1);
ProductCreateRequest productRequest = new ProductCreateRequest()
.name("Gold")
.startDate(startDate)
.endDate(endDate)
.description("Gold Product")
.sku("SKU3677");
Product newProduct =
zuoraClient.products().createProduct(productRequest);
- lang: JavaScript
label: Node
source: >-
const productRequest = {
name: "Gold",
sku: "SKU3677",
description: "Gold Product",
start_date: "2022-04-01",
end_date: "2032-04-01",
};
const newProduct = await
zuoraClient.products.createProduct(productRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/product'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:29:09-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:29:09-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-07-01'
end_date: '2032-07-01'
name: Software service
type: base
description: Software service - basic edition
sku: SKU-00011719
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/plans/{plan_id}:
get:
operationId: getPlan
summary: Retrieve a plan
tags:
- Plans
description: Retrieves the plan with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: plan_id
required: true
schema:
type: string
description: The plan number or plan Id.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePlan
summary: Update a plan
tags:
- Plans
description: >-
Updates the specified plan by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/planPatchRequest'
example:
custom_fields:
field__c: custom field value
name: SeedRatePlan
description: Update Name and Custom Field
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: plan_id
required: true
schema:
type: string
description: The plan number or plan Id.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/plans/8ad09f8a7e25bda3017e25dd7743705f"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "Updated Monthly Plan",
"description": "Updated Monthly plan of the Gold product",
"start_date": "2022-11-01",
"end_date": "2031-11-01"
}'
- lang: Java
label: Java
source: >-
Plan newPlan = zuoraClient.plans().createPlan(planRequest);
LocalDate newPlanStartDate = LocalDate.of(2022, 11, 1);
LocalDate newPlanEndDate = LocalDate.of(2031, 11, 1);
PlanPatchRequest planRequest = new PlanPatchRequest()
.name("Updated Monthly Plan")
.startDate(newPlanStartDate)
.endDate(newPlanEndDate)
.description("Updated Monthly plan of the Gold product");
Plan updatedPlan = zuoraClient.plans().updatePlan(newPlan.getId(),
planRequest);
- lang: JavaScript
label: Node
source: >-
const newPlan = await zuoraClient.plans.createPlan(planRequest);
const planUpdateReq = {
name: "Updated Monthly Plan",
description: "Updated Monthly plan of the Gold product",
start_date: "2022-11-01",
end_date: "2031-11-01",
};
const updatedPlan = await zuoraClient.plans.updatePlan(newPlan.id,
planUpdateReq);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
example:
id: 8ad08e018258a21701825f3d90310116
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:04:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deletePlan
summary: Delete a plan
tags:
- Plans
description: Permanently deletes a plan. It cannot be undone.
parameters:
- in: path
name: plan_id
required: true
schema:
type: string
description: The plan number or plan Id.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/plans:
get:
operationId: getPlans
summary: List plans
tags:
- Plans
description: >-
Returns a dictionary with a data property that contains an array of
plans, starting after the cursor, if used. Each entry in the array is a
separate plan object. If no more plans are available, the resulting
array will be empty. This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/planListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createPlan
summary: Create a plan
tags:
- Plans
description: Creates a new plan for an existing product.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/planCreateRequest'
example:
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: prices.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/plans"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "Monthly Plan",
"product_id": "2c94a116ef504f65b5ef1e9e9e8377e1",
"description": "Monthly plan of the Gold product",
"start_date": "2022-06-20",
"end_date": "2031-06-19",
"active_currencies": ["USD", "EUR"]
}'
- lang: Java
label: Java
source: |-
LocalDate planStartDate = LocalDate.of(2022, 6, 20);
LocalDate planEndDate = LocalDate.of(2031, 6, 19);
List<String> activeCurrencies = new ArrayList<String>();
activeCurrencies.add("USD");
activeCurrencies.add("EUR");
PlanCreateRequest planRequest = new PlanCreateRequest()
.name("Monthly Plan")
.productId(newProduct.getId())
.startDate(planStartDate)
.endDate(planEndDate)
.description("Monthly plan of the Gold product")
.activeCurrencies(activeCurrencies);
Plan newPlan = zuoraClient.plans().createPlan(planRequest);
- lang: JavaScript
label: Node
source: |-
const productId = newProduct.Id;
const planRequest = {
name: "Monthly Plan",
product_id: productId,
description: "Monthly plan of the Gold product",
start_date: "2022-06-20",
end_date: "2031-06-19",
active_currencies: ["USD", "EUR"],
};
const newPlan = await zuoraClient.plans.createPlan(planRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/plan'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T08:47:26-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T08:47:26-07:00'
custom_fields:
field__c: custom field value
start_date: '2022-08-01'
end_date: '2035-06-01'
name: SeedRatePlan
product_id: 8ad09fc28258af4a01825f2cd30871cd
active: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/prices/{price_id}:
get:
operationId: getPrice
summary: Retrieve a price
tags:
- Prices
description: Retrieves the price with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: price_id
required: true
schema:
type: string
description: Price Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/price'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchPrice
summary: Update a price
tags:
- Prices
description: >-
Updates the specified price by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/pricePatchRequest'
example:
name: SeedlingPlan
description: Patch plan
start_event: contract_effective
recognized_revenue_accounting_code: Subscription Revenue
deferred_revenue_accounting_code: Subscription Revenue
tax_inclusive: false
quantity: 1
min_quantity: 0
unit_of_measure: Bottle
max_quantity: 0
recurring:
'on': subscription_item_start_day
usage: false
interval: week
interval_count: 1
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
discount_level: plan
apply_discount_to:
- recurring
- one_time
- one_time
discount_percent: 50
price_base_interval: billing_period
custom_fields:
field__c: custom field value
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: price_id
required: true
schema:
type: string
description: Price Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/prices/8ad0877b7fb4e59b017fb7c23b746fce"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "Updated Price",
"description": "Updated Price Description",
"quantity": 1,
"unit_of_measure": "Bottle",
"recurring": {
"usage": false,
"interval": "week",
"interval_count": 1,
"alignment_behavior": "none",
"duration_interval": "subscription_term",
"duration_interval_count": 1
}
}'
- lang: Java
label: Java
source: >-
Recurring recurringComponent = new Recurring()
.usage(false)
.interval(IntervalEnum.WEEK)
.intervalCount(1)
.alignmentBehavior(AlignmentBehaviorEnum.NONE)
.durationInterval(DurationIntervalEnum.SUBSCRIPTION_TERM)
.durationIntervalCount(1);
PricePatchRequest updatePriceReq = new PricePatchRequest()
.name("Updated Price")
.description("Updated Price Description")
.quantity(new BigDecimal(1))
.unitOfMeasure("Bottle")
.recurring(recurringComponent);
Price updatedPrice =
zuoraClient.prices().patchPrice(newPrice.getId(), updatePriceReq);
- lang: JavaScript
label: Node
source: >-
const updatePriceReq = {
name: "Updated Price",
description: "Updated Price Description",
quantity: 1,
unit_of_measure: "Bottle",
recurring: {
usage: false,
interval: "week",
interval_count: 1,
alignment_behavior: "none",
duration_interval: "subscription_term",
duration_interval_count: 1
}
};
const updatedPrice = await
zuoraClient.prices.patchPrice(newPrice.Id, updatePriceReq);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/price'
example:
id: 8ad0877b7fb4e59b017fb7c23b746fce
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:17:56-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-03-23T10:10:34-07:00'
custom_fields:
field__c: custom field value
name: test
description: Test Description
recurring:
'on': subscription_item_start_day
usage: false
interval: week
interval_count: 1
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tax_inclusive: false
quantity: 0
discount_level: plan
discount_percent: 50
price_base_interval: billing_period
plan_id: 8ad09f8a7e25bda3017e25dd7743705f
charge_type: recurring
charge_model: discount_percentage
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deletePrice
summary: Delete a price
tags:
- Prices
description: Permanently deletes a price. It cannot be undone.
parameters:
- in: path
name: price_id
required: true
schema:
type: string
description: Price Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/prices:
get:
operationId: getPrices
summary: List prices
tags:
- Prices
description: >-
Returns a dictionary with a data property that contains an array of
prices, starting after the cursor, if used. Each entry in the array is a
separate price object. If no more prices are available, the resulting
array will be empty. This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/priceListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createPrice
summary: Create a price
tags:
- Prices
description: Creates a new price for an existing plan.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/priceCreateRequest'
example:
name: Recurring Perunit
description: Create Price
start_event: contract_effective
recurring:
recurring_on: account_cycle_date
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
recognized_revenue_accounting_code: Subscription Revenue
deferred_revenue_accounting_code: Subscription Revenue
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/prices"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"name": "Recurring Per Unit Price",
"unit_of_measure": "Each",
"unit_amounts": {
"USD": 100
},
"recurring": {
"interval": "month",
"interval_count": "1",
"timing": "in_advance"
},
"quantity": 1,
"plan_id": "2c921528ef504f65b5ef1e9e9e8362f2",
"description": "Reccuring per unit price of the monthly plan",
"start_event": "contract_effective",
"price_base_interval": "month",
"deferred_revenue_accounting_code": "Service Revenue",
"recognized_revenue_accounting_code": "Service Revenue"
}'
- lang: Java
label: Java
source: >2-
Map<String, BigDecimal> unitAmounts = new HashMap<String,
BigDecimal>();
unitAmounts.put("USD", new BigDecimal(100.0));
PriceCreateRequest priceRequest = new PriceCreateRequest()
.unitAmounts(unitAmounts)
.unitOfMeasure("Each")
.name("Recurring Per Unit Price")
.priceBaseInterval(PriceBaseIntervalEnum.MONTH)
.planId(newPlan.getId())
.description("Reccuring per unit price of the monthly plan")
.recurring(new Recurring()
.intervalCount(1)
.timing(TimingEnum.ADVANCE)
.interval(IntervalEnum.MONTH))
.quantity(new BigDecimal(1))
.startEvent(StartEventEnum.CONTRACT_EFFECTIVE)
.recognizedRevenueAccountingCode("Service Revenue")
.deferredRevenueAccountingCode("Service Revenue");
Price newPrice = zuoraClient.prices().createPrice(priceRequest);
- lang: JavaScript
label: Node
source: |-
const priceRequest = {
name: "Recurring Per Unit Price",
unit_of_measure: "Each",
unit_amounts: {
USD: 100
},
recurring: {
interval: "month",
interval_count: "1",
timing: "in_advance"
},
quantity: 1,
plan_id: "2c921528ef504f65b5ef1e9e9e8362f2",
description: "Reccuring per unit price of the monthly plan",
start_event: "contract_effective",
price_base_interval: "month",
recognized_revenue_accounting_code: "Service Revenue",
deferred_revenue_accounting_code: "Service Revenue"
};
const newPrice = await zuoraClient.prices.createPrice(priceRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/price'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T05:56:54-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-02T05:56:54-07:00'
custom_fields:
field__c: custom field value
name: Recurring Perunit
description: from Postman
recurring:
'on': subscription_item_start_day
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
duration_interval_count: 1
start_event: contract_effective
tiers_mode: graduated
tiers:
- up_to: 10
unit_amounts:
USD: 10
- unit_amounts:
USD: 7
tax_code: Avalara
tax_inclusive: false
unit_of_measure: Each
quantity: 15
price_base_interval: billing_period
plan_id: 8ad0877b813e5774018143f39e98059b
charge_type: recurring
charge_model: tiered
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payments/{payment_id}:
get:
operationId: getPayment
summary: Retrieve a payment
tags:
- Payments
description: Retrieves the payment with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_id
required: true
schema:
type: string
description: Identifier for the payment, either `payment_number` or `payment_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePayment
summary: Update a payment
tags:
- Payments
description: >-
Updates the specified payment by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentPatchRequest'
example:
description: update payment
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_id
required: true
schema:
type: string
description: Identifier for the payment, either `payment_number` or `payment_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/payments/8ad085518098b8b8018099e87ca616aa"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"description": "description of the payment"
}'
- lang: Java
label: Java
source: >-
Payment payment =
zuoraClient.payments().getPayment("8ad085518098b8b8018099e87ca616aa",
null, null);
PaymentPatchRequest paymentPatchRequest = new
PaymentPatchRequest().description("description of the payment");
Payment updatedPayment =
zuoraClient.payments().updatePayment(payment.getId(),
paymentPatchRequest);
- lang: Node
label: Node
source: >-
const payment = await
zuoraClient.payments.getPayment("8ad085518098b8b8018099e87ca616aa");
const paymentPatchRequest = {
description: "description of the payment"
};
const updatedPayment = await
zuoraClient.payments.updatePayment(payment.id, paymentPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 2c92c0fb711afdf001711bf371f3188f
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T09:38:03-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2020-03-27T05:24:31-07:00'
custom_fields:
field__c: custom field value
description: update payment
payment_number: P-00000033
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 224.66
payment_date: '2020-03-27'
payment_method_id: 8f64d4d7b1b989f6c571d931f84e0458
external: true
currency: USD
amount_applied: 0
remaining_balance: 224.66
amount_refunded: 0
state: canceled
gateway_state: not_submitted
state_transitions: {}
gateway_state_transitions: {}
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payments:
get:
operationId: getPayments
summary: List payments
tags:
- Payments
description: >-
Returns a dictionary with a data property that contains an array of
payments, starting after the cursor, if used. Each entry in the array is
a separate payment object. If no more payments are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T23:45:51-07:00'
created_by_id: 8ad095b88282409101828ab626fb2430
created_time: '2022-08-26T02:07:04-07:00'
custom_fields:
field__c: custom field value
reference_id: '2867259.919697461'
payment_number: P-0000270901234
account_id: 8ad09b7d8292b85d0182a4d6f875225a
amount: 5555
payment_date: '2022-08-26'
payment_method_id: 8ad09c4b82b063e20182b4663492151e
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 5542
amount_refunded: 13
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-26T02:07:05-07:00'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createPayment
summary: Create a payment
tags:
- Payments
description: Creates a new payment object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentCreateRequest'
example:
amount: 100
currency: USD
payment_date: '2022-09-09'
account_id: 2c92c0f96abc17de016abd62bd0c5854
payment_method_id: 2c92c0f9710b79bd01711219e3ed2d9a
gateway_id: 2c92c0f86a8dd422016a941ee0d82c7f
gateway_options:
key: test
value: test
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/payments"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"account_id": "2c92c0f96abc17de016abd62bd0c5854",
"amount": 50,
"currency": "USD",
"payment_date": "2022-03-08",
"payment_method_id": "8f64d4d7b1b989f6c571d931f84e0458",
"external": true
}'
- lang: Java
label: Java
source: >-
LocalDate paymentDate = LocalDate.of(2022, 3, 8);
PaymentCreateRequest paymentCreateRequest = new
PaymentCreateRequest()
.accountId("2c92c0f96abc17de016abd62bd0c5854")
.amount(new BigDecimal(50))
.currency("USD")
.paymentDate(paymentDate)
.paymentMethodId("8f64d4d7b1b989f6c571d931f84e0458")
.external(true);
Payment newPayment =
zuoraClient.payments().createPayment(paymentCreateRequest);
- lang: Node
label: Node
source: >-
const paymentCreateRequest = {
account_id: "2c92c0f96abc17de016abd62bd0c5854",
amount: 50,
currency: "USD",
payment_date: "2022-03-08",
payment_method_id: "8f64d4d7b1b989f6c571d931f84e0458",
external: true
};
const newPayment = await
zuoraClient.payments.createPayment(paymentCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 8ad09b7d8322303e0183231cc3e24df5
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T09:37:12-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-09T09:37:11-07:00'
custom_fields:
field__c: custom field value
reference_id: '8884632.901643027'
payment_number: P-00002718
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 100
payment_date: '2022-09-09'
payment_method_id: 2c92c0f9710b79bd01711219e3ed2d9a
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 100
amount_refunded: 0
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-09-09T09:37:12-07:00'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payments/{payment_id}/cancel:
post:
operationId: cancelPayment
summary: Cancel a payment
tags:
- Payments
description: Cancels an unapplied payment.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_id
required: true
schema:
type: string
description: Identifier for the payment, either `payment_number` or `payment_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X POST
"https://rest.apisandbox.zuora.com/v2/payments/8ad085518098b8b8018099e87ca616aa/cancel"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{}'
- lang: Java
label: Java
source: >-
Payment payment =
zuoraClient.payments().getPayment("8ad085518098b8b8018099e87ca616aa",
null, null);
Payment canceledPayment =
zuoraClient.payments().cancelPayment(payment.getId());
- lang: Node
label: Node
source: >-
const payment = await
zuoraClient.payments.getPayment("8ad085518098b8b8018099e87ca616aa");
const canceledPayment = await
zuoraClient.payments.cancelPayment(payment.id);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 8ad09b7d8322303e0183231cc3e24df5
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T10:41:37-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-09T09:37:11-07:00'
custom_fields:
field__c: custom field value
reference_id: '347763.3843209915'
payment_number: P-00002718
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 100
payment_date: '2022-09-09'
payment_method_id: 2c92c0f9710b79bd01711219e3ed2d9a
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 0
remaining_balance: 100
amount_refunded: 0
state: canceled
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: not_submitted
state_transitions:
canceled_time: '2022-09-09T10:41:37-07:00'
gateway_state_transitions:
submitted_time: '2022-09-09T09:37:12-07:00'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payments/{payment_id}/apply:
put:
operationId: applyPayment
summary: Apply a payment
tags:
- Payments
description: Applies a payment to one or more invoices or debit memos.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentApplyUnapplyRequest'
example:
effective_date: '2022-08-17'
billing_documents:
- type: debit_memo
id: 8ad088957f019d45017f04285beb067e
amount: 10
items:
- id: 8ad088957f019d45017f04285bfc067f
amount: 10
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_id
required: true
schema:
type: string
description: Identifier for the payment, either `payment_number` or `payment_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: apply
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 8ad09c4b82aa84900182ada00dca1e22
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-17T14:07:49-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-17T14:05:23-07:00'
custom_fields:
field__c: custom field value
description: payment created from API v2
bank_account_accounting_code: Credit Card
reference_id: '4600811.222845461'
payment_number: P-00002692
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
amount: 15
payment_date: '2022-08-17'
payment_method_id: 8ad0950c8292b8560182a75940b808cd
gateway_id: CC Gateway
external: false
currency: USD
state_transitions:
submitted_time: '2022-08-17T14:05:24-07:00'
amount_applied: 10
remaining_balance: 5
amount_refunded: 0
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payments/{payment_id}/unapply:
put:
operationId: unapplyPayment
summary: Unapply a payment
tags:
- Payments
description: Unapplies an applied payment.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentApplyUnapplyRequest'
example:
effective_date: '2022-08-30'
billing_documents:
- type: invoice
id: 8ad09c4b82699e8f01826a35705c1d3a
amount: 10
- type: invoice
id: 8ad093f27f54fa8d017f6b191ff02543
amount: 20
- type: invoice
id: 8ad0823f827dc6a801827efa3b721853
amount: 30
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: payment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `payment_number`, `payment_date`, `gateway_id`, `payment_method_id`, `payout_id`, `reference_id`, `second_reference_id`, `statement_descriptor_phone`, `state`, `statement_descriptor`, `account_id`, `amount`, `amount_applied`, `amount_refunded`, `remaining_balance`, `currency`, `description`, `authorization_id`, `external`, `gateway_order_id`, `gateway_reconciliation_status`, `gateway_reconciliation_reason`, `gateway_response`, `gateway_response_code`, `gateway_state`, `state_transitions`, `gateway_state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: payment_applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`amount`, `billing_document_id`, `billing_document_type`, `id`, `state`
</details>
- in: query
name: payment_applied_to_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_id
required: true
schema:
type: string
description: Identifier for the payment, either `payment_number` or `payment_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: unapply
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/payment'
example:
id: 8ad095b882e89fa50182ef9d275f002f
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-30T09:39:41-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-30T09:37:10-07:00'
custom_fields:
field__c: custom field value
reference_id: '9455369.375904325'
payment_number: P-00002711
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 120
payment_date: '2022-08-30'
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
gateway_id: Test Gateway
external: false
currency: USD
amount_applied: 60
remaining_balance: 60
amount_refunded: 0
state: processed
gateway_response_code: approve
gateway_response: This transaction has been approved by Test gateway.
gateway_state: submitted
state_transitions: {}
gateway_state_transitions:
submitted_time: '2022-08-30T09:37:10-07:00'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscription_plans/{subscription_plan_id}:
get:
operationId: getSubscriptionPlan
summary: Retrieve a subscription plan
tags:
- Subscription Plans
description: Retrieves the subscription plan with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: subscription_plan_id
required: true
schema:
type: string
description: Suscription Plan Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/subscription_plans/8ad085518193a90a01819687d45760e2'
--header 'Authorization: Bearer 7e6a7b1aac344c7f921c711c691981b0'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
SubscriptionPlan subscriptionPlanResponse =
zuoraClient.subscriptionPlans().getSubscriptionPlan(createdSubscriptionPlan.getId(),null,Collections.singletonList("subscription"),null);
System.out.println(subscriptionPlanResponse);
- lang: JavaScript
label: Node
source: >-
const subscriptionPlanResponse = await
zuoraClient.subscriptionPlans.getSubscriptionPlan('8ad085518193a90a01819687d45760e2');
console.log(subscriptionPlanResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPlan'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscription_plans:
get:
operationId: getSubscriptionPlans
summary: List subscription plans
tags:
- Subscription Plans
description: >-
Returns a dictionary with a data property that contains an array of
subscription plans, starting after cursor. Each entry in the array is a
separate object. If no more are available, the resulting array will be
empty. This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription_plan.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET
--url
'https://rest.apisandbox.zuora.com/v2/subscription_plans?expand%5B%5D=subscription'
--header 'Authorization: Bearer 7e6a7b1aac344c7f921c711c691981b0'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
SubscriptionPlanListResponse subscriptionPlansResponse =
zuoraClient.subscriptionPlans().getSubscriptionPlans(null,Collections.singletonList("subscription"),
null);
System.out.println(subscriptionPlansResponse);
- lang: JavaScript
label: Node
source: >-
const subscriptionPlansResponse = await
zuoraClient.subscriptionPlans.getSubscriptionPlans({
filter:['updated_time.GT:2022-06-30T00:00:00.000Z'],
expand:['subscription'],
});
console.log(subscriptionPlansResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionPlanListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
- id: 8ad08ccf8437067601843a7af4e64rq3
custom_fields:
field__c: custom field value
subscription_id: 8ad0823f8258a21901825f6dacbe6f90
plan_id: 8ad09f8a7c980e07017c9f396a9c53df
name: SeedRatePlan
subscription_items:
next_page: null
data:
- id: 8ad0823f8258a21901825f6dad046f9a
name: Test Recurring Per Unit
recurring:
'on': subscription_item_start_day
alignment_behavior: none
duration_interval: subscription_term
duration_interval_count: 1
interval: month
interval_count: 1
timing: in_advance
usage: false
price_id: 8ad084a67c9801a7017c9f3974237561
start_event: contract_effective
tax_inclusive: false
unit_of_measure: Each
quantity: 0
price_base_interval: billing_period
created_time: '2022-08-02T09:39:59-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-08-02T09:39:59-07:00'
subscription_plan_id: 8ad0823f8258a21901825f6dad046f99
custom_fields:
field__c: custom field value
start_date: '2022-08-02'
end_date: '2023-07-01'
active: true
state: active
unit_amount: 15
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/subscription_items:
get:
operationId: getSubscriptionItems
summary: List subscription items
tags:
- Subscription Items
description: List items contained in subscriptions.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: subscription_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: price.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option`
</details>
- in: query
name: subscription_plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`
</details>
- in: query
name: plan.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies`
</details>
- in: query
name: product.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `active`, `name`, `type`, `sku`, `description`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl --request GET --url 'https://rest.apisandbox.zuora.com/v2/subscription_items?filter%5B%5D=id.EQ%3A8ad0889d86da5d7f0186db4ad79f79dd&=' --header 'Authorization: Bearer 85fc74df4c09410980c3786752818649'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/subscriptionItemListResponse'
example:
next_page: null
data:
- id: 8ad0889d86da5d7f0186db4ad79f79e6
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-13T07:06:00-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-13T07:06:00-07:00'
custom_fields:
Price__c: '0'
custom_objects: {}
subscription_item_number: C-00050012
name: Recurring Perunit
description: from Postman
charged_through_date: '2023-04-01'
recurring:
recurring_on: account_cycle_date
'on': account_cycle_date
usage: false
interval: month
interval_count: 1
alignment_behavior: none
timing: in_advance
duration_interval: subscription_term
active: true
state: active
start_event: contract_effective
tax_inclusive: false
quantity: 1
amount: 0.25
price_base_interval: billing_period
charge_model: flat_fee
charge_type: recurring
price_id: 8ad0991583bacd6d0183c86d3b1832ba
subscription_plan_id: 8ad0889d86da5d7f0186db4ad79f79db
start_date: '2022-09-01'
processed_through_date: '2023-03-01'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/refunds:
get:
operationId: getRefunds
summary: List refunds
tags:
- Refunds
description: >-
Returns a dictionary with a data property that contains an array of
refunds, starting after cursor. Each entry in the array is a separate
object. If no more are available, the resulting array will be empty.
This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: refund.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: refund_applied_to_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `credit_memo_item_id`, `taxation_item_id`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/refundListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createRefund
summary: Create a refund
tags:
- Refunds
description: Creates a new refund object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/refundCreateRequest'
example:
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 5
refund_date: '2022-09-07'
refund_method_type: cash
external: true
payment_id: 8ad0887e83163bc7018319b1b6573d80
statement_descriptor: statement_descriptor
statement_descriptor_phone: statement_descriptor
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: refund.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: refund_applied_to_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `credit_memo_item_id`, `taxation_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl -X POST "https://rest.apisandbox.zuora.com/v2/refunds"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"description": "description of the refund"
}'
- lang: Java
label: Java
source: >-
String accountId = "8ad09b7d8292b85d0182a4d6f875225a";
String paymentId = newPayment.getId();
RefundCreateRequest refundRequest = new RefundCreateRequest()
.amount(new BigDecimal(10))
.accountId(accountId)
.paymentId(paymentId)
.external(false);
Refund refund =
zuoraClient.refunds().createRefund(refundRequest);
- lang: JavaScript
label: Node
source: >-
const refundCreateRequest = {
account_id: "8ad09b7d8292b85d0182a4d6f875225a",
amount: 10,
payment_id: "8ad0887e82d94f5d0182d967a49c1a63",
external: false
};
const newRefund = await
zuoraClient.refunds.createRefund(refundCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
example:
id: 8ad08aef83163bc5018319cfc9e00711
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T14:16:32-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T14:16:32-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 5
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-00001109
state_transitions: {}
state: processed
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/refunds/{refund_id}:
get:
operationId: getRefund
summary: Retrieve a refund
tags:
- Refunds
description: Retrieves the refund with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: refund.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: refund_applied_to_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `credit_memo_item_id`, `taxation_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: refund_id
required: true
schema:
type: string
description: Identifier for the payment, either `refund_number` or `refund_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-07T13:45:01-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-07T13:45:01-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 10
refund_date: '2022-09-07'
payment_method_id: 8f64d4d73a20057bce2d3aedf9212bd1
reason_code: Standard Refund
external: true
gateway_state: not_submitted
refund_number: R-0000110801234
state_transitions: {}
state: processed
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateRefund
summary: Update a refund
tags:
- Refunds
description: >-
Updates the specified refund by setting the values of the parameters
passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/refundPatchRequest'
example:
description: Reverse Payment
reason_code: Payment Reversal
custom_fields:
field__c: custom field value
bank_account_account: Credit Card
unapplied_payment_account: Credit Card
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: refund.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: refund_applied_to_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `credit_memo_item_id`, `taxation_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: refund_id
required: true
schema:
type: string
description: Identifier for the payment, either `refund_number` or `refund_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl -X PATCH
"https://rest.apisandbox.zuora.com/v2/refunds/8ad095dd8442830b01845130b4006e14"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
-d '{
"description": "description of the refund"
}'
- lang: JavaScript
label: Node
source: >-
const refund = await
zuoraClient.refunds.getRefund("8ad095dd8442830b01845130b4006e14");
const refundPatchRequest = {
description: "description of the refund"
};
const updatedRefund = await
zuoraClient.refunds.updateRefund(refund.id, refundPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
example:
id: 8ad09bce82e89fa10182efb70be25e15
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T09:48:50-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-30T10:05:27-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 20
refund_date: '2022-08-30'
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
reason_code: Payment Reversal
external: false
gateway_response: This transaction has been approved by Test gateway.
gateway_response_code: approve
gateway_state: submitted
refund_number: R-00001100
state_transitions: {}
state: processed
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteRefund
summary: Delete a refund
tags:
- Refunds
description: >-
Permanently deletes a refund. Note that once you have deleted a refund,
it cannot be undone.
parameters:
- in: path
name: refund_id
required: true
schema:
type: string
description: Identifier for the payment, either `refund_number` or `refund_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
https://rest.apisandbox.zuora.com/v2/refunds/R-00001116
--header 'Authorization: Bearer
20a9b6b903324ecd90e77baa1fb8714e' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.refunds().deleteRefund("R-00001116");
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteRefundResponse = await
zuoraClient.refunds.deleteRefund('R-00001116');
console.log(deleteRefundResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/refunds/{refund_id}/cancel:
post:
operationId: cancelRefund
summary: Cancel a refund
tags:
- Refunds
description: Cancels an unapplied refund.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: refund.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `refund_date`, `external`, `gateway_id`, `gateway_reconciliation_reason`, `gateway_reconciliation_status`, `gateway_response`, `gateway_response_code`, `gateway_state`, `comment`, `payment_method_id`, `payout_id`, `reason_code`, `reference_id`, `refund_method_type`, `refund_number`, `statement_descriptor`, `statement_descriptor_phone`, `state`, `state_transitions`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: payment_method.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `type`, `account_id`, `bank_identification_number`, `device_session_id`, `ip_address`, `maximum_payment_attempts`, `payment_retry_interval`, `state`, `use_default_retry_rule`, `existing_mandate`, `last_failed_sale_transaction_time`, `last_transaction_time`, `last_transaction_status`, `number_of_consecutive_failures`, `total_number_of_processed_payments`, `total_number_of_error_payments`, `billing_details`, `card`, `apple_pay`, `google_pay`, `ach_debit`, `cc_ref`, `paypal_adaptive`, `paypal_express_native`, `paypal_express`, `sepa_debit`, `betalings_debit`, `autogiro_debit`, `bacs_debit`, `au_becs_debit`, `nz_becs_debit`, `pad_debit`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: refund_applied_to_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `credit_memo_item_id`, `taxation_item_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: refund_id
required: true
schema:
type: string
description: Identifier for the payment, either `refund_number` or `refund_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/refunds/R-00001114/cancel
--header 'Authorization: Bearer
20a9b6b903324ecd90e77baa1fb8714e' --header 'Content-Type:
application/json'
--data '{}'
- lang: Java
label: Java
source: >2-
Refund refundResponse =
zuoraClient.refunds().cancelRefund("R-00001114", null, null);
System.out.println(creditMemoResponse);
- lang: JavaScript
label: Node
source: >-
const canceledRefund = await
zuoraClient.refunds.cancelRefund("R-00001114");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/refund'
example:
id: 8ad09bce82e89fa10182efb70be25e15
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T13:50:54-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-08-30T10:05:27-07:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 20
refund_date: '2022-08-30'
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
reason_code: Payment Reversal
external: false
comment: Reverse Payment
gateway_response: This transaction has been approved by Test gateway.
gateway_response_code: approve
gateway_state: not_submitted
refund_number: R-00001100
state_transitions:
canceled_time: '2023-01-18T13:50:54-08:00'
state: canceled
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/custom_objects/{custom_object_type}:
get:
operationId: getCustomObjects
summary: List custom objects
tags:
- Custom Objects
description: Returns a list of your custom objects.
parameters:
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values will be those available in your tenant.
- in: query
name: custom_object[custom_object_type].fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values and `custom_object_types` will be those
available in your tenant.
- in: query
name: custom_object.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
</details>
- in: path
name: custom_object_type
required: true
schema:
type: string
description: Custom Object Definition Type
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/custom_objects/car'
--header 'Authorization: Bearer
7e6a7b1aac344c7f921c711c691981b0' --header 'Content-Type:
application/json'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/listCustomObjectResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createCustomObject
summary: Create a custom object
tags:
- Custom Objects
description: Creates a new custom object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customObjectCreateRequest'
example:
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values will be those available in your tenant.
- in: query
name: custom_object[custom_object_type].fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values and `custom_object_types` will be those
available in your tenant.
- in: query
name: custom_object.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
</details>
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the 'Filter lists' section
of the [Quickstart API
Tutorial](https://developer.zuora.com/quickstart-api/tutorial/overview/)
for detailed instructions.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: path
name: custom_object_type
required: true
schema:
type: string
description: Custom Object Definition Type
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/custom_object'
example:
id: 663726af-ad23-45ff-9aa5-5144ded53280
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-09T16:56:05.241Z'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T16:56:05.241Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/custom_objects/{custom_object_type}/{custom_object_id}:
get:
operationId: getCustomObject
summary: Retrieve a custom object
tags:
- Custom Objects
description: Retrieves the custom object with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values will be those available in your tenant.
- in: query
name: custom_object[custom_object_type].fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values and `custom_object_types` will be those
available in your tenant.
- in: query
name: custom_object.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
</details>
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the 'Filter lists' section
of the [Quickstart API
Tutorial](https://developer.zuora.com/quickstart-api/tutorial/overview/)
for detailed instructions.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: path
name: custom_object_type
required: true
schema:
type: string
description: Custom Object Definition Type
- in: path
name: custom_object_id
required: true
schema:
type: string
description: Custom Object Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/custom_objects/car/07a0903d-dd59-480e-a6ae-37fb4486f002'
--header 'Authorization: Bearer
b33c3733c75c486298f520483bdcdcc0' --header 'Content-Type:
application/json'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/custom_object'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-08-04T03:49:06.051Z'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-08-04T03:49:06.051Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateCustomObject
summary: Update a custom object
tags:
- Custom Objects
description: >-
Updates the specified custom object by setting the values of the
parameters passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/customObjectPatchRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values will be those available in your tenant.
- in: query
name: custom_object[custom_object_type].fields[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
description: >-
Allows you to specify which fields are returned in the response.
Accepted `field` values and `custom_object_types` will be those
available in your tenant.
- in: query
name: custom_object.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
</details>
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the 'Filter lists' section
of the [Quickstart API
Tutorial](https://developer.zuora.com/quickstart-api/tutorial/overview/)
for detailed instructions.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: path
name: custom_object_type
required: true
schema:
type: string
description: Custom Object Definition Type
- in: path
name: custom_object_id
required: true
schema:
type: string
description: Custom Object Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/custom_object'
example:
id: 663726af-ad23-45ff-9aa5-5144ded53280
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-09-09T16:56:05.241Z'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-09-09T16:56:05.241Z'
name__c: X4
brand__c: BMW
engine__c: Turbo-4SL
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteCustomObject
summary: Delete a custom object
tags:
- Custom Objects
description: Permanently deletes a custom object. It cannot be undone.
parameters:
- in: path
name: custom_object_type
required: true
schema:
type: string
description: Custom Object Definition Type
- in: path
name: custom_object_id
required: true
schema:
type: string
description: Custom Object Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/custom_objects/car/07a0903d-dd59-480e-a6ae-37fb4486f002'
--header 'Authorization: Bearer
b33c3733c75c486298f520483bdcdcc0' --header 'Content-Type:
application/json'
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_runs/{bill_run_id}:
get:
operationId: getBillRun
summary: Retrieve a bill run
tags:
- Bill Runs
description: Retrieves the bill run information with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: bill_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: bill_run_id
required: true
schema:
type: string
description: >-
Identifier for the bill run, either `bill_run_number` or
`bill_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/bill_runs/8ad08c8485a701b30185a782a30a6c88
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
BillRun billRunResponse =
zuoraClient.billRuns().getBillRun(newBillRun.getId(),null);
System.out.println(billRun);
- lang: JavaScript
label: Node
source: >-
const billRunResponse = await
zuoraClient.billRuns.getBillRun('BR-00000066');
console.log(billRunResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRun'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteBillRun
summary: Delete a bill run
tags:
- Bill Runs
description: >-
Deletes a bill run. Only the bill runs with the `canceled` status can be
deleted.
parameters:
- in: path
name: bill_run_id
required: true
schema:
type: string
description: >-
Identifier for the bill run, either `bill_run_number` or
`bill_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/bill_runs/8f64d4d7fa661677e277dcb1ef8ee8de'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.billRuns().deleteBillRun(newBillRun.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteBillRunResponse = await
zuoraClient.billRuns.deleteBillRun('8f64d4d7fa661677e277dcb1ef8ee8de');
console.log(deleteBillRunResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_runs:
get:
operationId: getBillRuns
summary: List bill runs
tags:
- Bill Runs
description: >-
Returns an array of bill runs. Each entry in the array is a separate
bill run object. If no more bill runs are available, the resulting
array will be empty. This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: bill_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/bill_runs --header
'Authorization: Bearer dcf5d050c6e7493688859d04da581938'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
BillRunListResponse BillRunListResponse =
zuoraClient.billRuns().getBillRuns(null,null,null);
System.out.println(BillRunListResponse);
- lang: JavaScript
label: Node
source: |-
const billRunListResponse = await zuoraClient.billRuns.getBillRuns({
filter: [
'state.EQ:completed',
]
});
console.log(billRunListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/BillRunListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createBillRun
summary: Create a bill run
tags:
- Bill Runs
description: Creates a bill run on a single account, or a batch of customer accounts.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BillRunCreateRequest'
example:
renew: true
batches:
- Batch1
day_of_month: AllBillCycleDays
charges_excluded: OneTime
invoice_date: '2022-01-12'
email_zero_amount_invoices: true
target_date: '2022-01-12'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: bill_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/bill_runs --header
'Content-Type: application/json' --header 'x-donut-auth: Bearer
4f3a8ca735f54e9e8ea118c086dc34e1' --data '{
"renew": true,
"batches": "Batch1",
"day_of_month": "AllBillCycleDays",
"charges_excluded": "OneTime",
"invoice_date": "2022-01-12",
"email_zero_amount_invoices": true,
"target_date": "2022-01-12"
}'
- lang: Java
label: Java
source: >-
LocalDate todayDate = LocalDate.now()
BillRunCreateRequest billRunCreateRequest = new
BillRunCreateRequest()
.renew(true)
.batches("Batch1"),
.dayOfMonth("AllBillCycleDays")
.chargesExcluded("OneTime")
.invoiceDate(todayDate)
.targetDate(todayDate);
BillRun newBillRun =
zuoraClient.billRuns().createBillRun(billRunCreateRequest);
- lang: JavaScript
label: Node
source: >-
const billRunCreateRequest = {
renew: true,
batches: "Batch1",
day_of_month: "AllBillCycleDays",
charges_excluded: "OneTime",
invoice_date: "2022-01-12",
email_zero_amount_invoices: true,
target_date: "2022-01-12"
};
const newBillRun = await
zuoraClient.billRuns.createBillRun(billRunCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRun'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_runs/{bill_run_id}/post:
post:
operationId: postBillRun
summary: Post a bill run
tags:
- Bill Runs
description: >-
Posts a bill run. Only the bill runs with the `completed` status can be
posted.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BillRunPostRequest'
example:
invoice_date: '2022-01-11'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: bill_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: bill_run_id
required: true
schema:
type: string
description: >-
Identifier for the bill run, either `bill_run_number` or
`bill_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: "\ncurl --request POST --url https://rest.apisandbox.zuora.com/v2/bill_runs/BR-00000022/post --header 'Content-Type: application/json' --header 'x-donut-auth: Bearer 4f3a8ca735f54e9e8ea118c086dc34e1' --data '{\n\t\t \"invoice_date\":\"2023-01-11\"\n }'\n "
- lang: Java
label: Java
source: >-
LocalDate todayDate = LocalDate.now()
BillRunPostRequest billRunPostRequest = new BillRunPostRequest()
.invoiceDate(todayDate);
BillRun postedBillRun =
zuoraClient.billRuns().postBillRun(billRunPostRequest);
- lang: JavaScript
label: Node
source: >-
const billRunPostRequest = {
invoice_date: "2023-01-12",
};
const postedBillRun = await
zuoraClient.billRuns.postBillRun(billRunPostRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRun'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_runs/{bill_run_id}/cancel:
post:
operationId: cancelBillRun
summary: Cancel a bill run
tags:
- Bill Runs
description: >-
Cancels a bill run. Only the bill run that has no posted invoices can be
canceled.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: bill_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `email`, `post`, `renew`, `batches`, `day_of_month`, `charges_excluded`, `invoice_date`, `email_zero_amount_invoices`, `target_date`, `bill_run_number`, `bill_run_time`, `invoices_sent`, `last_invoice_sent_time`, `accounts_processed`, `invoices_generated`, `credit_memos_generated`, `state`, `name`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: bill_run_id
required: true
schema:
type: string
description: >-
Identifier for the bill run, either `bill_run_number` or
`bill_run_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/bill_runs/8f64d4d7fa661677e277dcb1ef8ee8de/cancel
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer 4f3a8ca735f54e9e8ea118c086dc34e1' --data
'{}'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.billRuns().cancelBillRun(newBillRun.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const cancelBillRunResponse = await
zuoraClient.billRuns.cancelBillRun('8f64d4d7fa661677e277dcb1ef8ee8de');
console.log(cancelBillRunResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRun'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-12T11:44:23-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:54-08:00'
custom_fields: {}
custom_objects: {}
email: false
post: false
renew: true
day_of_month: '01'
bill_run_number: BR-00000066
bill_run_time: '2023-01-12T11:43:55-08:00'
invoice_date: '2022-01-12'
target_date: '2022-01-12'
state: completed
batches: AllBatches
charges_excluded: OneTime
email_zero_amount_invoices: true
invoices_sent: false
accounts_processed: 5
invoices_generated: 4
credit_memos_generated: 1
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/usage_records:
get:
operationId: getUsageRecords
summary: List usage records
tags:
- Usage Records
description: >-
Returns an array of usage records. Each entry in the array is a separate
Usage object. If no more usages are available, the resulting
array will be empty. This request should never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: usage_record.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/usage_records' --header
'Authorization: Bearer d8a7f4d2a5ef4c3eba8618cf99593e26'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
ListUsageResponse usageListResponse =
zuoraClient.usageRecords().getUsages(null,null);
System.out.println(usageListResponse);
- lang: JavaScript
label: Node
source: |-
const usagesResponse = await zuoraClient.usageRecords.getUsages({
filter: [
'unit_of_measure.EQ:USD',
],
})
console.log(usagesResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/listUsageResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
- id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
- id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
- id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
- id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createUsage
summary: Create a usage record
tags:
- Usage Records
description: Creates a new Usage object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/usageCreateRequest'
example:
unit_of_measure: Each
quantity: 4
start_time: '2022-01-01T00:00:00+00:00'
account_id: 2c92c0f974e9737a0175034cc0cc10c1
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: usage_record.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/usage_records --header
'Authorization: Bearer 8d17d8e8cc36419998a205896d670ed2'
--header 'Content-Type: application/json' --data '{
"unit_of_measure": "Each",
"quantity": "4",
"start_time": "2022-01-01T00:00:00+00:00",
"account_id": "2c92c0f974e9737a0175034cc0cc10c1"
}'
- lang: Java
label: Java
source: >2-
UsageCreateRequest usageCreateRequest = new UsageCreateRequest()
.account_id("2c92c0f974e9737a0175034cc0cc10c1")
.unit_of_measure("Each")
.quantity("4")
.start_time("2022-01-01T00:00:00+00:00");
Usage newUsage =
zuoraClient.usageRecords().createUsage(usageCreateRequest);
- lang: JavaScript
label: Node
source: >-
const usageCreateRequest = {
unit_of_measure: "Each",
quantity: "4",
start_time: "2022-01-01T00:00:00+00:00",
account_id: "2c92c0f974e9737a0175034cc0cc10c1"
}
};
const newUsage = await
zuoraClient.usageRecords.createUsage(usageCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/usage'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/usage_records/{id}:
get:
operationId: getUsage
summary: Retrieve a usage record
tags:
- Usage Records
description: Retrieves the usage with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: usage_record.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: id
required: true
schema:
type: string
description: Usage Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/usage_records/8ad099158561c2b901857ecbd9131422
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Usage usageResponse =
zuoraClient.usageRecords().getUsage(newUsage.getId(),null);
System.out.println(usageResponse);
- lang: JavaScript
label: Node
source: >-
const usageResponse = await
zuoraClient.usageRecords.getUsage('8ad099158561c2b901857ecbd9131422');
console.log(usageResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/usage'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: Each
state: pending
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateUsage
summary: Update a usage record
tags:
- Usage Records
description: >-
Updates the usage record. Any fields on the object not provided in the
request are not changed.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/usagePatchRequest'
example:
unit_of_measure: USD
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: usage_record.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `account_number`, `subscription_item_id`, `subscription_item_number`, `subscription_id`, `subscription_number`, `unit_of_measure`, `description`, `end_time`, `state`, `start_time`, `quantity`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: subscription.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `order_number`
</details>
- in: query
name: subscription_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: id
required: true
schema:
type: string
description: Usage Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/usage_records/8ad08cbd8586721c018587d293aa3752
--header 'Authorization: Bearer
06a297740b184fc384bc57cbe8a04e53' --header 'Content-Type:
application/json' --data '{
"unit_of_measure": "USD",
}'
- lang: Java
label: Java
source: >-
Usage oldUsage =
zuoraClient.usageRecords().getUsage("8ad0950c82aa847f0182ae9563f46b84",
null);
UsagePatchRequest usagePatchRequest = new UsagePatchRequest()
.unit_of_measure("USD");
Usage updatedUsage =
zuoraClient.usageRecords().updateUsage(oldUsage.getId(),usagePatchRequest);
- lang: JavaScript
label: Node
source: >-
const usagePatchRequest = {
unit_of_measure: "USD",
};
const updatedUsage = await
zuoraClient.usageRecords.updateUsage('8ad0950c83927b4301839e70a6611e0c',
usagePatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/usage'
example:
id: 8ad08cbd8586721c018587d293aa3752
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-06T08:03:22-08:00'
custom_fields:
field__c: custom field value
custom_objects: {}
account_number: RC-00000093
account_id: 2c92c0f974e9737a0175034cc0cc10c1
description: Creates a usage
quantity: 4
subscription_id: 2c92c0f974e9736d017503559cc76d22
unit_of_measure: USD
state: pending
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteUsage
summary: Delete a usage record
tags:
- Usage Records
description: Permanently deletes a usage object. It cannot be undone.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: Usage Id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/usage_records/2c92c0f86a8dd422016a9e7a70116b0d'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.usageRecords().deleteUsage(newUsage.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteUsageResponse = await
zuoraClient.usageRecords.deleteUsage('8ad087e284427311018447079d9e4efe');
console.log(deleteUsageResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/orders:
get:
operationId: getOrders
summary: List orders
tags:
- Orders
description: Lists all or a subset of orders in your tenant.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order_actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
</details>
- in: query
name: line_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/orders --header
'Authorization: Bearer bd13987b7a434286b1b6f75dcb8e3d01' --header
'Content-Type: application/json'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/orderListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createOrder
summary: Create an order
tags:
- Orders
description: >-
You can use this operation to create subscriptions and make changes to
existing subscriptions. You can also use this operation to create order
line items. <p> Note that the following limitations apply to this
operation: <ul> <li>Up to 50 subscriptions are allowed in a
single call.</li> <li>Up to 100 order line items are allowed in an
order.</li> <li>Up to 1000 orders are allowed on a
subscription.</li> </ul>
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderCreateRequest'
example:
description: Create an new order with a new account
account_data:
name: Zuora's Order Account
currency: USD
bill_to:
first_name: Amy
last_name: Lawrence
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
state: California
country: USA
postal_code: '94064'
work_phone: (888) 976-9056
work_email: amy.lawrence@zuora.com
payment_method:
type: card
billing_details:
name: John Doe
card:
card_number: '41111111111'
brand: visa
expiry_month: 11
expiry_year: 2023
security_code: '123'
order_date: '2023-01-01'
subscriptions:
- initial_term:
interval_count: 1
interval: year
type: termed
renewal_term:
type: evergreen
start_on:
contract_effective: '2023-01-01'
subscription_plans:
- plan_id: 8ad09fc2843cc2fb01843f4504b761af
prices:
- price_id: 8ad0887e850fc589018512981a1b4acb
quantity: 20
start_date: '2023-01-01'
end_date: '2023-12-01'
- price_id: 8ad0877b84ade9350184af7ccff43ad2
quantity: 5
start_date: '2023-01-15'
end_date: '2023-06-15'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order_actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
</details>
- in: query
name: line_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: "\ncurl --request POST --url https://rest.apisandbox.zuora.com/v2/orders --header 'Authorization: Bearer addae50e361d464584d57818d8d9d1d9' --header 'Content-Type: application/json' --data '{\n \"description\": \"Create a new account with subscriptions\",\n \"account_data\": {\n \"name\": \"ABCD Account\",\n \"currency\": \"USD\",\n \"bill_to\": {\n \"first_name\": \"Amy\",\n \"last_name\": \"Lawrence\",\n \"address\": {\n \"line1\": \"101 Redwood Shores Parkway\",\n \"line2\": \"\",\n \"city\": \"Redwood City\",\n \"state\": \"California\",\n \"country\": \"USA\",\n \"postal_code\": \"94064\"\n },\n \"work_phone\": \"(888) 976-9056\",\n \"work_email\": \"amy.lawrence@zuora.com\"\n },\n \"payment_method\": {\n \"type\": \"card\",\n \"billing_details\": {\n \"name\": \"John Doe\"\n },\n \"card\": {\n \"card_number\": \"41111111111\",\n \"brand\": \"visa\",\n \"expiry_month\": 11,\n \"expiry_year\": 2023,\n \"security_code\": \"123\"\n }\n }\n },\n \"order_date\": \"2023-01-01\",\n \"subscriptions\": [\n {\n \"initial_term\": {\n \"interval_count\": 1,\n \"interval\": \"year\",\n \"type\": \"termed\"\n },\n \"renewal_term\": {\n \"type\": \"evergreen\"\n },\n \"start_on\": {\n \"contract_effective\": \"2023-01-01\"\n },\n \"subscription_plans\": [\n {\n \"plan_id\": \"8ad09fc2843cc2fb01843f4504b761af\",\n \"prices\": [\n {\n \"price_id\": \"8ad0887e850fc589018512981a1b4acb\",\n \"quantity\": 20,\n \"start_date\": \"2023-01-01\",\n \"end_date\": \"2023-12-31\" \n },\n {\n \"price_id\": \"8ad0877b84ade9350184af7ccff43ad2\",\n \"quantity\": 5,\n \"start_date\": \"2023-02-15\",\n \"end_date\": \"2023-06-15\"\n }\n ]\n }\t\t\t\t\n ]\n },\n {\n \"initial_term\": {\n \"interval_count\": 3,\n \"interval\": \"year\",\n \"type\": \"termed\"\n },\n \"renewal_term\": {\n \"type\": \"evergreen\"\n },\n \"start_on\": {\n \"contract_effective\": \"2023-01-01\"\n },\n \"subscription_plans\": [\n {\n \"plan_id\": \"8ad0877b84f775280184f8047ab011e9\",\n \"prices\": [\n {\n \"price_id\": \"8ad09bce84f7896b0184f80caa622518\",\n \"quantity\": 2,\n \"start_date\": \"2023-01-01\" \n }\n ]\n }\t\t\t\t\n ]\n }\n ]\n }' \n "
- lang: Java
label: Java
source: >2-
LocalDate orderDate = LocalDate.of(2023,1,1);
LocalDate startDate1 = LocalDate.of(2023,1,1);
LocalDate endDate1 = LocalDate.of(2023,12,31);
LocalDate startDate2 = LocalDate.of(2023,2,15);
LocalDate endDate2 = LocalDate.of(2023,6,15);
// First subscription request
SubscriptionItemCreateRequest subscriptionItemCreateRequest1 = new
SubscriptionItemCreateRequest()
.priceId("8ad0887e850fc589018512981a1b4acb")
.quantity(new BigDecimal(20))
.startDate(startDate1)
.endDate(endDate1);
SubscriptionItemCreateRequest subscriptionItemCreateRequest2 = new
SubscriptionItemCreateRequest()
.priceId("8ad0877b84ade9350184af7ccff43ad2")
.quantity(new BigDecimal(5))
.startDate(startDate2)
.endDate(endDate2);
ArrayList prices = new ArrayList();
prices.add(subscriptionItemCreateRequest1);
prices.add(subscriptionItemCreateRequest2);
SubscriptionPlanCreateRequest subscriptionPlanRequest1 = new
SubscriptionPlanCreateRequest()
.planId("8ad09fc2843cc2fb01843f4504b761af")
.prices(prices);
PostSubscriptionOrderRequest subscriptionRequest1 = new
PostSubscriptionOrderRequest()
.initialTerm(new Term().interval(Term.IntervalEnum.YEAR).intervalCount(1).type(Term.TypeEnum.TERMED))
.renewalTerm(new Term().type(Term.TypeEnum.EVERGREEN))
.putCustomFieldsItem("TestSubscriptionRequired__c", "testValue")
.startOn(new StartOn().contractEffective(startDate1))
.subscriptionPlans(Collections.singletonList(subscriptionPlanRequest1));
// Second subscription request
SubscriptionItemCreateRequest subscriptionItemCreateRequest3 = new
SubscriptionItemCreateRequest()
.priceId("8ad09bce84f7896b0184f80caa622518")
.startDate(startDate1);
SubscriptionPlanCreateRequest subscriptionPlanRequest = new
SubscriptionPlanCreateRequest()
.planId("8ad09fc2843cc2fb01843f4504b761af")
.prices(Collections.singletonList(subscriptionItemCreateRequest3));
PostSubscriptionOrderRequest subscriptionRequest2 = new
PostSubscriptionOrderRequest()
.initialTerm(new Term().interval(Term.IntervalEnum.YEAR).intervalCount(1).type(Term.TypeEnum.TERMED))
.renewalTerm(new Term().type(Term.TypeEnum.EVERGREEN))
.startOn(new StartOn().contractEffective(startDate1))
.subscriptionPlans(Collections.singletonList(subscriptionPlanRequest));
ArrayList multiSubscriptions = new ArrayList();
multiSubscriptions.add(subscriptionRequest1);
multiSubscriptions.add(subscriptionRequest2);
// New account information
AccountContactCreateRequest contactCreateRequest = new
AccountContactCreateRequest()
.firstName("Amy")
.lastName("Lawrence")
.workEmail("amy.lawrence@zuora.com")
.workPhone("(888) 976-9056")
.address(new Address()
.country("USA")
.state("California")
.postalCode("94065")
.line1("101 Redwood Shores Parkway")
.city("Redwood City"));
AccountPaymentMethodRequest paymentMethodRequest = new
AccountPaymentMethodRequest()
.type(AccountPaymentMethodRequest.TypeEnum.CARD)
.billingDetails(new BillingDetails().name("John Doe"))
.card(new Card()
.cardNumber("41111111111")
.brand(Card.BrandEnum.VISA)
.expiryMonth(new BigDecimal(11))
.expiryYear(new BigDecimal(2025))
.securityCode("123"));
AccountCreateRequest accountCreateRequest = new
AccountCreateRequest()
.name("ABCD Account")
.billTo(contactCreateRequest)
.currency("USD")
.paymentMethod(paymentMethodRequest);
//Create an order request
OrderCreateRequest orderCreateRequest = new OrderCreateRequest()
.accountData(accountCreateRequest)
.description("Create a new account with subscriptions")
.orderDate(orderDate)
.subscriptions(multiSubscriptions);
Order order = zuoraClient.orders().createOrder(orderCreateRequest);
- lang: JavaScript
label: Node
source: >-
const subscriptionPlans = [{
plan_id: '8ad09fc2843cc2fb01843f4504b761af',
prices: [
{
price_id: '8ad0887e850fc589018512981a1b4acb',
quantity: 20,
start_date: '2023-01-01',
end_date: '2023-12-01',
},
{
price_id: '8ad0877b84ade9350184af7ccff43ad2',
quantity: 5,
start_date: '2022-12-15',
end_date: '2023-06-15',
},
]
}];
const oli = {
name: 'Setup fee',
type: 'fee',
unit_amount: 10,
quantity: 5,
start_date: '2023-01-01',
};
const subscriptionRequest = {
initial_term: {
interval_count:1,
interval: 'year',
type: 'termed',
},
renewal_term:{
type: 'evergreen',
},
subscription_plans: subscriptionPlans,
start_on:{
contract_effective: "2023-01-01",
}
};
const orderRequest = {
description: 'Create an order with a recurring item and an order line item',
account_number: 'RC-00020939',
order_date: '2023-01-01',
line_items: [oli],
subscriptions: [subscriptionRequest],
};
const createdOrder = await
zuoraClient.orders.createOrder(orderRequest);
console.log(createdOrder);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/order'
example:
id: 8ad0934e861a27bd018624b93d2f11d9
order_number: O-00021762
order_date: '2023-01-01'
state: pending
created_time: '2023-02-05T19:16:04-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-02-05T19:16:05-08:00'
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
description: Create a new subscription with a new account
account_id: 8ad0934e861a27bd018624b93ca211cb
line_items: []
subscriptions:
- id: 8ad0934e861a27bd018624b93e6211f6
subscription_number: A-S00013739
state: pending_activation
account_id: 8ad0934e861a27bd018624b93ca211cb
invoice_owner_account_id: 8ad0934e861a27bd018624b93ca211cb
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2023-01-01'
end_date: '2024-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2023-01-01'
end_date: '2024-01-01'
contract_effective: '2023-01-01'
invoice_separately: false
latest_version: true
order_number: O-00021762
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-02-05T19:16:05-08:00'
updated_time: '2023-02-05T19:16:05-08:00'
actions:
- type: create_subscription
action_id: 8ad0934e861a27bd018624b93d4a11df
sequence: 0
start_on:
contract_effective: '2023-01-01'
subscription_plans:
- id: 8ad0934e861a27bd018624b93ee0120b
plan_id: 8ad09fc2843cc2fb01843f4504b761af
subscription_items:
- id: 8ad0934e861a27bd018624b93ee01214
subscription_item_number: C-00049408
name: Recurring Yearly Plan 2
description: Subscription under yearly plan
recurring:
'on': subscription_start_day
alignment_behavior: none
interval: year
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 1
recurring_on: subscription_start_day
price_id: 8ad09bce8455cd0c01845e8d3c152199
start_event: contract_effective
tax_inclusive: false
unit_of_measure: License
quantity: 1
price_base_interval: billing_period
created_time: '2023-02-05T19:16:05-08:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-02-05T19:16:05-08:00'
subscription_plan_id: 8ad0934e861a27bd018624b93ee0120b
custom_fields:
Price__c: '0'
start_date: '2023-01-01'
end_date: '2024-01-01'
active: true
state: active
unit_amount: 0
- id: 8ad0934e861a27bd018624b93ee01213
subscription_item_number: C-00049406
name: Recurring Yearly Plan 2
description: Subscription under yearly plan
recurring:
'on': subscription_start_day
alignment_behavior: none
interval: year
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 1
recurring_on: subscription_start_day
price_id: 8ad08e0184ade9350184af5bf1f46007
start_event: contract_effective
tax_inclusive: false
unit_of_measure: License
quantity: 1
price_base_interval: billing_period
created_time: '2023-02-05T19:16:05-08:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-02-05T19:16:05-08:00'
subscription_plan_id: 8ad0934e861a27bd018624b93ee0120b
custom_fields:
Price__c: '0'
start_date: '2023-01-01'
end_date: '2024-01-01'
active: true
state: active
unit_amount: 150
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/orders/{order_id}:
get:
operationId: getOrder
summary: Retrieve an order
tags:
- Orders
description: >-
Use this operation to retrieve the detailed information about a specific
order.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order_actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
</details>
- in: query
name: line_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: order_id
required: true
schema:
type: string
description: Identifier for the order, either `order_number` or `order_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/orders/O-00021614 --header
'Authorization: Bearer 210901c2dd6c4c748a09e3a0fcaee12f'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: |2-
Order orderResponse = zuoraClient.orders().getOrder("O-00021614");
System.out.println(orderResponse);
- lang: JavaScript
label: Node
source: >-
const getOrderResponse = await
zuoraClient.orders.getOrder('O-00021614');
console.log(getOrderResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/order'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteOrder
summary: Delete an order
tags:
- Orders
description: Deletes an order.
parameters:
- in: path
name: order_id
required: true
schema:
type: string
description: Identifier for the order, either `order_number` or `order_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request DELETE --url
https://rest.apisandbox.zuora.com/v2/orders/8ad08d298727e378018734a158575662
--header 'Authorization: Bearer
cd91b5ee8dab40bf9060d77511b1daad' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.orders().deleteOrder(newOrder.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteOrderResponse = await
zuoraClient.orders.deleteOrder('8ad087e284427311018447079d9e4efe');
console.log(deleteOrderResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/orders/preview:
post:
operationId: createOrderPreview
summary: Preview an order
tags:
- Orders
description: >-
Retrieves the preview of the order delta metrics and invoice items of a
specified order. Preview for subscriptions and order line items are both
supported. This operation is only an order preview and no order is
created. <p> Note that the following limitations apply to this
operation: <ul> <li>Up to 50 subscriptions are allowed in a
single call.</li> <li>Up to 100 order line items are allowed in an
order preview.</li> </ul>
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderPreviewCreateRequest'
example:
description: Preview an order request
account_data:
currency: USD
bill_cycle_day: 1
sold_to:
first_name: Bella
last_name: Lawrence
address:
line1: 101 Redwood Shores Parkway
city: Redwood City
state: California
country: USA
postal_code: '94065'
work_phone: (888) 976-9056
work_email: amy.lawrence@gmail.com
metrics:
- delta_metrics
subscriptions:
- initial_term:
interval_count: 6
interval: month
type: termed
renewal_term:
type: termed
interval: month
interval_count: 3
start_on:
contract_effective: '2023-01-01'
subscription_plans:
- plan_id: 8ad09fc2843cc2fb01843f4504b761af
prices:
- price_id: 8ad0887e850fc589018512981a1b4acb
quantity: 20
unit_amount: 20
start_date: '2023-01-01'
end_date: '2023-06-30'
- price_id: 8ad0877b84ade9350184af7ccff43ad2
quantity: 5
unit_amount: 40
start_date: '2023-02-15'
end_date: '2023-06-15'
required: true
parameters:
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: preview
x-code-samples:
- lang: Curl
label: cURL
source: "\ncurl --request POST --url https://rest.apisandbox.zuora.com/v2/orders/preview --header 'Authorization: Bearer 3d21521a674b4410b0cf4db2580feb9d' --header 'Content-Type: application/json' --data '{\n \"description\": \"Preview an order request\",\n \"account_data\": {\n \"currency\": \"USD\",\n \"bill_cycle_day\": 1,\n \"sold_to\": {\n \"first_name\": \"Bella\",\n \"last_name\": \"Lawrence\",\n \"address\": {\n \"line1\": \"101 Redwood Shores Parkway\",\n \"line2\": \"\",\n \"city\": \"Redwood City\",\n \"state\": \"California\",\n \"country\": \"USA\",\n \"postal_code\": \"94065\"\n },\n \"work_phone\": \"(888) 976-9056\",\n \"work_email\": \"bella.lawrence@gmail.com\"\n }\n },\n \"metrics\": [\"delta_metrics\"],\n \"subscriptions\": [\n {\n \"initial_term\": {\n \"interval_count\": 1,\n \"interval\": \"month\",\n \"type\": \"termed\"\n },\n \"renewal_term\": {\n \"type\": \"termed\",\n \"interval\": \"month\",\n \"interval_count\": 2,\n },\n \"start_on\": {\n \"contract_effective\": \"2023-01-01\"\n },\n \"subscription_plans\": [\n {\n \"plan_id\": \"8ad09fc2843cc2fb01843f4504b761af\",\n \"prices\": [\n {\n \"price_id\": \"8ad0887e850fc589018512981a1b4acb\",\n \"quantity\": 20,\n \"start_date\": \"2023-01-01\",\n \"end_date\": \"2023-12-01\" \n },\n {\n \"price_id\": \"8ad0877b84ade9350184af7ccff43ad2\",\n \"quantity\": 5,\n \"start_date\": \"2023-02-15\",\n \"end_date\": \"2023-06-15\"\n }\n ]\n }\t\t\t\t\n ]\n }\n ]\n }'"
- lang: Java
label: Java
source: >2-
LocalDate startDate1 = LocalDate.of(2023,1,1);
LocalDate endDate1 = LocalDate.of(2023,12,31);
LocalDate startDate2 = LocalDate.of(2023,2,15);
LocalDate endDate2 = LocalDate.of(2023,6,15);
// New subscription request
SubscriptionItemCreateRequest subscriptionItemCreateRequest1 = new
SubscriptionItemCreateRequest()
.priceId("8ad0887e850fc589018512981a1b4acb")
.quantity(new BigDecimal(20))
.startDate(startDate1)
.endDate(endDate1);
SubscriptionItemCreateRequest subscriptionItemCreateRequest2 = new
SubscriptionItemCreateRequest()
.priceId("8ad0877b84ade9350184af7ccff43ad2")
.quantity(new BigDecimal(5))
.startDate(startDate2)
.endDate(endDate2);
ArrayList prices = new ArrayList();
prices.add(subscriptionItemCreateRequest1);
prices.add(subscriptionItemCreateRequest2);
SubscriptionPlanCreateRequest subscriptionPlanRequest = new
SubscriptionPlanCreateRequest()
.planId("8ad09fc2843cc2fb01843f4504b761af")
.prices(prices);
PostSubscriptionOrderRequest newSubscriptionRequest = new
PostSubscriptionOrderRequest()
.initialTerm(new Term()
.interval(Term.IntervalEnum.MONTH)
.intervalCount(1)
.type(Term.TypeEnum.TERMED))
.renewalTerm(new Term()
.type(Term.TypeEnum.TERMED)
.intervalCount(2)
.interval(Term.IntervalEnum.MONTH))
.startOn(new StartOn().contractEffective(startDate1))
.subscriptionPlans(Collections.singletonList(subscriptionPlanRequest));
// New account request
AccountContactCreateRequest contactCreateRequest = new
AccountContactCreateRequest()
.firstName("Bella")
.lastName("Lawrence")
.workEmail("bella.lawrence@gmail.com")
.workPhone("(888) 976-9056")
.address(new Address()
.country("USA")
.state("California")
.postalCode("94065")
.line1("101 Redwood Shores Parkway")
.city("Redwood City"));
SubscriptionPreviewAccountRequest accountCreateRequest = new
SubscriptionPreviewAccountRequest()
.billCycleDay(1)
.soldTo(contactCreateRequest)
.currency("USD");
// Preview order request
OrderPreviewCreateRequest orderPreviewRequest = new
OrderPreviewCreateRequest()
.description("Preview an order request")
.accountData(accountCreateRequest)
.metrics(Collections.singletonList(OrderPreviewCreateRequest.MetricsEnum.DELTA_METRICS))
.subscriptions(Collections.singletonList(newSubscriptionRequest));
Map<String, Object> orderPreview =
zuoraClient.orders().createOrderPreview(orderPreviewRequest);
System.out.println(orderPreview);
- lang: JavaScript
label: Node
source: >-
const soldToContact = {
first_name: 'Bella',
last_name: 'Lawrence',
work_phone: '(888) 976-9056',
work_email: 'bella.lawrence@gmail.com',
address:{
line1: '101 Redwood Shores Parkway',
city: 'Redwood City',
state: 'California',
country: 'USA',
},
};
const account = {
sold_to: soldToContact,
currency: 'USD',
bill_cycle_day: 1,
};
const subscription_plans = [{
plan_id: '8ad09fc2843cc2fb01843f4504b761af',
prices: [
{
price_id: '8ad0887e850fc589018512981a1b4acb',
quantity: 20,
start_date: '2023-01-01',
end_date: '2023-12-01',
},
{
price_id: '8ad0877b84ade9350184af7ccff43ad2',
quantity: 5,
start_date: '2022-12-15',
end_date: '2023-06-15',
},
]
}];
const subscriptionRequest = {
initial_term: {
interval_count:1,
interval: 'month',
type: 'termed',
},
renewal_term:{
type: 'termed',
interval: 'month',
interval_count: 2,
},
subscription_plans: subscription_plans,
start_on:{
contract_effective: "2023-01-01",
},
};
const orderPreviewRequest = {
description: 'Description of order preview',
account_data: account,
order_date: '2023-01-01',
metrics: ['delta_metrics'],
subscriptions: [subscriptionRequest],
};
const previewedOrder = await
zuoraClient.orders.createOrderPreview(orderPreviewRequest);
console.log(JSON.stringify(previewedOrder));
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/orderPreviewResponse'
example:
subscriptions:
- subscription_number: 'null'
actions:
- action_id: 8ad09b21861a27a1018624c3ed4f0eab
action: create_subscription
sequence: 0
subscription_items:
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ece
price_id: 8ad09bce8455cd0c01845e8d3c152199
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 0
net_amount: 0
currency: USD
mrr:
gross_amount: 0
net_amount: 0
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ec6
price_id: 8ad0877b843cb3df01843fa3790579ea
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 74.383561644
net_amount: 74.383561644
currency: USD
mrr:
gross_amount: 12.5
net_amount: 12.5
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ecc
price_id: 8ad08e018455bb3801845e8ce6c273a0
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 74.383561644
net_amount: 74.383561644
currency: USD
mrr:
gross_amount: 12.5
net_amount: 12.5
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ecd
price_id: 8ad08e0184ade9350184af5bf1f46007
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 74.383561644
net_amount: 74.383561644
currency: USD
mrr:
gross_amount: 12.5
net_amount: 12.5
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ec8
price_id: 8ad0877b84ade9350184af7ccff43ad2
start_date: '2023-02-15'
end_date: '2023-06-15'
tcb:
gross_amount: 65.594730145
net_amount: 65.594730145
currency: USD
mrr:
gross_amount: 16.666666667
net_amount: 16.666666667
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570eca
price_id: 8ad0887e850fc589018512981a1b4acb
start_date: '2023-01-01'
end_date: '2023-06-30'
tcb:
gross_amount: 197.260273973
net_amount: 197.260273973
currency: USD
mrr:
gross_amount: 33.333333333
net_amount: 33.333333333
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ec9
price_id: 8ad0887e84a430860184abfe77b15964
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 74.383561644
net_amount: 74.383561644
currency: USD
mrr:
gross_amount: 12.5
net_amount: 12.5
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ecb
price_id: 8ad08e018455bb3801845e8cc56d723a
start_date: '2023-01-01'
end_date: '2023-07-01'
tcb:
gross_amount: 74.383561644
net_amount: 74.383561644
currency: USD
mrr:
gross_amount: 12.5
net_amount: 12.5
currency: USD
- subscription_item_id: 8ad09b21861a27a1018624c3ee570ec7
price_id: 8ad0877b843cb3df01843fa9a8dc3d82
start_date: '2023-01-01'
end_date: '2023-01-02'
tcb:
gross_amount: 1.5
net_amount: 1.5
currency: USD
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/orders/{order_id}/activate:
post:
operationId: activateOrder
summary: Activate an order
tags:
- Orders
description: Activates a draft order.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order_actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
</details>
- in: query
name: line_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: order_id
required: true
schema:
type: string
description: Identifier for the order, either `order_number` or `order_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
'http://localhost:3000/orders/8ad0934e8727f642018734b6230c4ddd/activate?order.fields%5B%5D=id%2C%20state%2C%20order_number'
--header 'Authorization: Bearer
cd91b5ee8dab40bf9060d77511b1daad'
- lang: Java
label: Java
source: >2-
Order orderResponse =
zuoraClient.orders().activateOrder("O-00021614");
System.out.println(orderResponse);
- lang: JavaScript
label: Node
source: >-
const activateOrderResponse = await
zuoraClient.orders.activateOrder('O-00021614');
console.log(activateOrderResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/order'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
order_number: O-0002341801234
order_date: '2022-01-01'
state: complete
category: sale
created_time: '2023-04-14T06:37:13-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
custom_fields: {}
description: description of test account
account_id: 8ad0934e86da6aca0186db46d29a2cee
subscriptions:
- id: 8ad08d29877fdeea01877ffbff293f04
subscription_number: A-S00013987
state: active
account_id: 8ad0823f8455bb400184633077e63aaf
invoice_owner_account_id: 8ad0934e86da6aca0186db46d29a2cee
auto_renew: false
version: 1
initial_term:
type: termed
interval_count: 1
interval: year
current_term:
type: termed
start_date: '2022-01-01'
end_date: '2023-01-01'
interval_count: 1
interval: year
renewal_term:
type: evergreen
start_date: '2022-01-01'
end_date: '2023-01-01'
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
invoice_separately: false
latest_version: true
order_number: O-00023418
custom_fields:
TestSubscriptionRequired__c: testValue
Cancel_Reason_Code__c: Customer Initiated
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-14T06:37:14-07:00'
updated_time: '2023-04-14T06:37:14-07:00'
billing_document_settings: {}
actions:
- action_id: 8ad08d29877fdeea01877ffbfe943ef6
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
subscription_plans:
next_page: null
data:
- id: 8ad08d29877fdeea01877ffbff6b3f0f
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff6b3f10
subscription_item_number: C-00050253
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
duration_interval: year
duration_interval_count: 2
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff6b3f0f
custom_fields:
Price__c: '0'
start_date: '2022-10-13'
end_date: '2023-01-01'
active: false
state: expired
unit_amount: 50
- id: 8ad08d29877fdeea01877ffbff473f0a
plan_id: 8ad0877b83ac56660183ae82d4373c8b
subscription_items:
- id: 8ad08d29877fdeea01877ffbff473f0b
subscription_item_number: C-00050252
name: Recurring - Unit Amount Upgrade
recurring:
'on': _1
alignment_behavior: none
interval: month
interval_count: 1
timing: in_advance
usage: false
recurring_on: _1
price_id: 8ad0991583ac6e130183ae83026637a7
tax_inclusive: false
unit_of_measure: Each
quantity: 10
price_base_interval: billing_period
created_time: '2023-04-14T06:37:14-07:00'
charge_model: per_unit
charge_type: recurring
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-14T06:37:14-07:00'
subscription_plan_id: 8ad08d29877fdeea01877ffbff473f0a
custom_fields:
Price__c: '0'
start_date: '2022-09-30'
end_date: '2022-10-13'
active: false
state: expired
unit_amount: 0
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/orders/{order_id}/cancel:
post:
operationId: cancelOrder
summary: Cancel an order
tags:
- Orders
description: Cancels a draft order.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderCancellationRequest'
example:
cancel_reason: Incorrect order details
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
</details>
- in: query
name: order_actions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
</details>
- in: query
name: subscriptions.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
</details>
- in: query
name: line_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: subscription_plans.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
</details>
- in: query
name: subscription_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: order_id
required: true
schema:
type: string
description: Identifier for the order, either `order_number` or `order_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/orders/8ad08d298727e378018734a158575662/cancel
--header 'Authorization: Bearer
cd91b5ee8dab40bf9060d77511b1daad' --header 'Content-Type:
application/json' --data '{
"cancel_reason": "Incorrect order details"
}'
- lang: Java
label: Java
source: >-
OrderCancellationRequest orderCancellationRequest = new
OrderCancellationRequest()
.cancelReason("Incorrect order details");
Order orderResponse = zuoraClient.orders().cancelOrder("O-00021614",
orderCancellationRequest);
System.out.println(orderResponse);
- lang: JavaScript
label: Node
source: >-
const orderCancellationRequest = {
cancel_reason: "Incorrect order details"
};
const orderResponse = await
zuoraClient.orders.cancelOrder("O-00021614",
orderCancellationRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/orderCancelResponse'
example:
id: 8ad08d298727e378018734a158575662
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-30T15:26:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-30T15:26:41-07:00'
custom_fields:
TestField__c: test
order_number: O-00023191
order_date: '2023-01-01'
description: description of test account
account_id: 8ad09e208727f63f018734233f4e39bb
subscriptions:
- custom_fields:
testField__c: test
auto_renew: false
latest_version: false
invoice_separately: false
version: 0
billing_document_settings:
sequence_set_id: 8ad08d298727e3780187df158575664
template_id: 8ad08d298727e359618734a158575664
actions:
- action_id: 8ad08d298727e378018734a158575664
type: create_subscription
sequence: 0
start_on:
contract_effective: '2022-01-01'
service_activation: '2022-01-01'
customer_acceptance: '2022-01-01'
state: canceled
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}:
get:
operationId: getInvoice
summary: Retrieve an invoice
tags:
- Invoices
description: Retrieves the invoice with the given invoice ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/invoices/8ad0855180f9da510180fbf80db40c79"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
Invoice invoiceResponse =
zuoraClient.invoices().getInvoice(newInvoice.getId(),null);
System.out.println(invoiceResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchInvoice
summary: Update an invoice
tags:
- Invoices
description: >-
Updates an invoice by setting the values of the specified fields. Any
fields not provided in the request remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/invoicePatchRequest'
example:
description: Updated invoice
document_date: '2023-01-23'
pay: false
custom_fields:
InvoiceWFProcessed__c: 2
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/invoices/8ad0852985cf047e0185d0c4ce891591
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer e7965be7723641fa8fc49b304d1f853e' --data
'{
"description": "Updated invoice",
"document_date": "2023-01-23",
"pay": true,
"custom_fields": {
"InvoiceWFProcessed__c": 2
}
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
invoicePatchRequest invoicePatchRequest = new invoicePatchRequest()
.description("Updated invoice")
.documentDate(todayDate)
.pay(true)
.customFields(new HashMap<String, String>() {{
put("InvoiceWFProcessed__c", "2");
}});
Invoice updatedInvoice =
zuoraClient.invoices().patchInvoice(invoicePatchRequest);
- lang: JavaScript
label: Node
source: >-
const invoicePatchRequest = {
description: "Updated invoice",
document_date: "2023-01-23",
pay: true,
custom_fields: {
InvoiceWFProcessed__c: 2,
},
};
const updatedInvoice = await
zuoraClient.invoices.patchInvoice(invoicePatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
example:
id: 8ad0852985cf047e0185d0c4ce891591
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-23T10:53:11-08:00'
created_by_id: 2c92c0f971c65e010171c79a08423ccc
created_time: '2023-01-20T12:00:37-08:00'
custom_fields:
InvoiceWFProcessed__c: '2'
EmailSentWorkflow__c: Unprocessed
LateFeeApplied__c: 'False'
account_id: 8ad09b7a7b3a62b9017b55d7387a72f8
description: Updated invoice
due_date: '2023-01-23'
document_date: '2023-01-23'
invoice_number: INV00008312
state_transitions: {}
state: draft
total: 100
subtotal: 100
tax: 0
remaining_balance: 100
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteInvoice
summary: Delete an invoice
tags:
- Invoices
description: Deletes an invoice that has not been canceled.
parameters:
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl --request DELETE --url https://rest.apisandbox.zuora.com/v2/invoices/INV00008122/delete --header 'Content-Type: application/json'
- lang: Java
label: Java
source: |2-
Invoice deleteInvoice = zuoraClient.invoice().deleteInvoice("INV00008122", null);
- lang: JavaScript
label: Node
source: |2-
const deleteInvoice = await zuoraClient.invoice.deleteInvoice("INV00008122");
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices:
get:
operationId: getInvoices
summary: List invoices
tags:
- Invoices
description: >-
Returns a dictionary with a data property that contains an array of
invoices, starting after cursor. Each entry in the array is a separate
invoice object. If no more invoices are available, the resulting array
will be empty.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl -X GET "https://rest.sandbox.na.zuora.com/v2/invoices"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
InvoiceListResponse invoiceListResponse =
zuoraClient.invoices().getinvoices(null,Collections.singletonList("account"),null);
System.out.println(invoiceListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createInvoice
summary: Create an invoice
tags:
- Invoices
description: Creates an invoice for an account.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceCreateRequest'
example:
account_id: 2c92c0f96abc17de016abd62bd0c5854
pay: false
description: Invoice Create
document_date: '2020-02-01'
custom_fields:
field__c: custom field value
post: true
items:
- amount: 10
name: Charge with tax amount
service_start: '2022-07-26'
taxation_items:
- name: tax
amount: 12
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
amount_exempt: 2
tax_inclusive: false
tax_rate_type: amount
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices --header
'Authorization: Bearer 7ab413058c18422fa391214a1b586f4a'
--header 'Content-Type: application/json' --data '{
"account_id": "8ad0934e85ab06a10185ac52f9363911",
"description": "new invoice",
"document_date": "2023-01-01",
"post":true,
"items": [
{
"amount": 300,
"booking_reference": "PE2FGW",
"name": "Recurring - Unit Amount Upgrade",
"description": "A new invoice item",
"service_start": "2023-01-01"
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
InvoiceItemCreateRequest invoiceItemRequest = new
InvoiceItemCreateRequest()
.amount(new BigDecimal(10.25))
.bookingReference("PE2FGW")
.name("Recurring - Unit Amount Upgrade")
.description("A new invoice item")
.serviceStart("2023-01-01");
InvoiceCreateRequest invoiceRequest = new InvoiceCreateRequest()
.accountId("8ad09c4b8262e38101826441928c1162")
.description("new invoice")
.documentDate(todayDate)
.post(true)
.items(Collections.singletonList(invoiceItemRequest));
Invoice newInvoice =
zuoraClient.invoices().createInvoice(invoiceRequest);
- lang: JavaScript
label: Node
source: "\nconst invoiceRequest = {\n account_id: '2c92c0f96abc17de016abd62bd0c5854',\n description: 'new invoice',\n document_date: '2023-01-01',\n post: true,\n items: [{\n amount: 300,\n booking_reference: 'PE2FGW',\t\n name: 'Recurring - Unit Amount Upgrade'\n service_start: '2022-09-01',\n }]\n}; \nconst newInvoice = await zuoraClient.invoices.createInvoice(invoiceRequest);\n "
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 8ad09bce80507dab0180688bdabc20cb
updated_time: '2023-01-31T05:22:16-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-31T05:22:15-08:00'
custom_fields:
field__c: custom field value
account_id: 8ad08d2986023f88018607fe0b27650d
due_date: '2022-08-01'
document_date: '2022-08-01'
invoice_number: INV0000831501234
state_transitions:
posted_at: '2023-01-31T05:22:16-08:00'
posted_by_id: 8ad09bce80507dab0180688bdabc20cb
state: draft
total: 751.5
subtotal: 751.5
tax: 0
remaining_balance: 751.5
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoice_items:
get:
operationId: getInvoiceItems
summary: List invoice items
tags:
- Invoices
description: Retrieves information about all items of invoices.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl -X GET "https://rest.sandbox.na.zuora.com/v2/invoice_items"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: |2-
InvoiceItemListResponse invoiceItemListResponse = zuoraClient.invoiceItems().getInvoiceItems(null, null, null);
System.out.println(invoiceItemListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceItemListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/reverse:
post:
operationId: reverseInvoice
summary: Reverse an invoice
tags:
- Invoices
description: Reverses a posted invoice.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/invoiceReverseRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: reverse
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices/8ad0852985cf047e0185d0c4c78814dd/reverse
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer 025b1016656c414291cdb8eab069cb49' --data
'{
"apply_date": "2023-01-24",
"document_date": "2023-01-24"
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
InvoiceReverseRequest invoiceReverseRequest = new
InvoiceReverseRequest()
.applyDate(todayDate)
.documentDate(todayDate);
Invoice reversedInvoice =
zuoraClient.invoices().reverseInvoice(invoiceReverseRequest);
- lang: JavaScript
label: Node
source: >-
const invoiceReverseRequest = {
apply_date: "2023-01-24",
document_date: "2023-01-24"
};
const reversedInvoice = await
zuoraClient.invoices.reverseInvoice(invoiceReverseRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/post:
post:
operationId: postInvoice
summary: Post an invoice
tags:
- Invoices
description: Opens a draft invoice.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices/INV00008312/post
--header 'Content-Type: application/json' --header 'Authorization:
Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{}'
- lang: Java
label: Java
source: >2-
Invoice postInvoice =
zuoraClient.invoice().postInvoice("INV00008312", null);
- lang: JavaScript
label: Node
source: >2-
const postInvoice = await
zuoraClient.invoice.postInvoice("INV00008312");
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/unpost:
post:
operationId: unpostInvoice
summary: Unpost an invoice
tags:
- Invoices
description: >-
Unposts an open invoice that has not been applied or refunded, and
changes its `state` to `draft`.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: unpost
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices/INV00008312/unpost
--header 'Content-Type: application/json' --header 'Authorization:
Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{}'
- lang: Java
label: Java
source: >2-
Invoice unpostInvoice =
zuoraClient.invoice().unpostInvoice("INV00008312", null);
- lang: JavaScript
label: Node
source: >2-
const unpostInvoice = await
zuoraClient.invoice.unpostInvoice("INV00008312");
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/email:
post:
operationId: emailInvoice
summary: Email an invoice
tags:
- Invoices
description: Emails an email to your customer.
parameters:
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-group-parameters: true
responses:
'204':
description: Default Response
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/pay:
post:
operationId: payInvoice
summary: Pay an invoice
tags:
- Invoices
description: Pays an invoice using an existing payment method.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/payInvoiceRequest'
example:
amount: 22
currency: USD
payment_date: '2023-01-31'
account_id: 2c92c0f96abc17de016abd62bd0c5854
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
gateway_id: 2c92c0f86a8dd422016a941ee0d82c7f
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: pay
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices/8ad08d2985c4e1580185c66663924318/pay
--header 'Content-Type: application/json' --data '{
"amount": 22,
"currency": "USD",
"payment_date": "2023-01-31",
"account_id": "2c92c0f96abc17de016abd62bd0c5854",
"payment_method_id": "8ad08ccf8292a2d20182a95408ac6530",
"gateway_id": "2c92c0f86a8dd422016a941ee0d82c7f"
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
InvoicePayRequest payInvoiceRequest = new InvoicePayRequest()
.amount(22)
.accountId("8ad09c4b8262e38101826441928c1162")
.paymentDate(todayDate)
.paymentMethodId("8ad08ccf8292a2d20182a95408ac6530")
.gatewayId("2c92c0f86a8dd422016a941ee0d82c7f");
Invoice payInvoice =
zuoraClient.invoice().payInvoice(payInvoiceRequest);
- lang: JavaScript
label: Node
source: >2-
const payInvoiceRequest = {
amount: 22,
currency: "USD",
payment_date: "2023-01-31",
account_id: "2c92c0f96abc17de016abd62bd0c5854",
payment_method_id: "8ad08ccf8292a2d20182a95408ac6530",
gateway_id: "2c92c0f86a8dd422016a941ee0d82c7f",
};
const payInvoice = await
zuoraClient.invoice.payInvoice(payInvoiceRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
example:
id: 8ad08dc986023f76018608da69e8606a
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-31T09:22:57-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-31T09:22:57-08:00'
payment_number: P-00002779
payment_date: '2023-01-31'
gateway_id: Test Gateway
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
reference_id: '6168540.740581938'
state: posted
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 22
amount_refunded: 0
remaining_balance: 0
currency: USD
gateway_response: This transaction has been approved by Test gateway.
gateway_response_code: approve
gateway_state: submitted
custom_fields:
field__c: custom field value
state_transitions: {}
gateway_state_transitions:
submitted_time: '2023-01-31T09:22:57-08:00'
custom_objects: {}
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/cancel:
post:
operationId: cancelInvoice
summary: Cancel an invoice
tags:
- Invoices
description: >-
Cancels an invoice. Only the invoice with the `draft` status can be
canceled.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `balance`, `due_date`, `invoice_number`, `posted_by_id`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `paid`, `past_due`, `document_date`, `amount_paid`, `amount_refunded`, `payment_terms`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/invoices/INV00008314/cancel
--header 'Content-Type: application/json' --header
'Authorization: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data
'{}'
- lang: Java
label: Java
source: >2-
Invoice cancelledInvoice =
zuoraClient.invoice().cancelInvoice("INV00008314", null);
- lang: JavaScript
label: Node
source: >2-
const cancelledInvoice = await
zuoraClient.invoice.cancelInvoice("INV00008314");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
example:
id: 8ad09e2085eda8be0185ef854c636659
invoice_number: INV00008314
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-26T11:19:28-08:00'
updated_time: '2023-01-26T11:21:46-08:00'
state_transitions: {}
state: uncollectible
description: standalone invoice created from API v2
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
total: 200
subtotal: 200
tax: 0
remaining_balance: 200
paid: false
past_due: true
document_date: '2022-08-05'
due_date: '2022-09-01'
custom_fields:
field__c: custom field value
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/invoices/{invoice_id}/write-off:
post:
operationId: writeOffInvoice
summary: Write off an invoice
tags:
- Invoices
description: Writes off an invoice
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/writeOffRequest'
example:
document_date: '2023-02-15'
reason_code: Write-off
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: invoice_id
required: true
schema:
type: string
description: Identifier for the invoices, either `invoice_number` or `invoice_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad08d29865429bb0186568fc35b4b2a
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-02-15T11:31:47-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-02-15T11:31:47-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0fb7a85d63b017a8d767caf6f98
document_date: '2023-02-15'
reason_code: Write-off
invoice_id: 8ad08a9d7d9fbdda017da034e47c26bc
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000703
amount_refunded: 0
state_transitions:
posted_time: '2023-02-15T11:31:47-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 100
subtotal: 100
tax: 0
balance: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos/{debit_memo_id}:
get:
operationId: getDebitMemo
summary: Retrieve a debit memo
tags:
- Debit Memos
description: Retrieves the debit memo with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/debit_memo/8ad0855180f9da510180fbf80db40c79"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
DebitMemo debitMemoResponse =
zuoraClient.debitmemo().getDebitMemo(newDebitMemo.getId(),null);
System.out.println(debitMemoResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchDebitMemo
summary: Update a debit memo
tags:
- Debit Memos
description: >-
Updates a debit memo by setting the values of the specified fields. Any
fields not provided in the request remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemoPatchRequest'
example:
description: Updated debit memo
pay: false
due_date: '2023-01-20'
document_date: '2023-01-20'
reason_code: Charge Dispute
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/debit_memos/8ad08dc985aaee970185bd81e4024e3e
--header 'Content-Type: application/json' --header 'x-donut-auth:
Bearer 920896f0ac024b108cbe34e57ee3f457' --data '{
"description": "Updated debit memo",
"pay": false,
"due_date": "2023-01-20",
"document_date": "2023-01-20",
"reason_code": "Charge Dispute"
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
DebitMemoPatchRequest debitMemoPatchRequest = new
debitMemoPatchRequest()
.description("Updated debit memo")
.pay(false)
.dueDate(todayDate)
.documentDate(todayDate)
.reasonCode("Charge Dispute");
DebitMemo updatedDebitMemo =
zuoraClient.debitMemos().patchDebitMemo(debitMemoPatchRequest);
- lang: JavaScript
label: Node
source: >-
const debitMemoPatchRequest = {
description: "Updated debit memo",
pay: false,
due_date: "2023-01-20",
document_date: "2023-01-20",
reason_code: "Charge Dispute",
};
const updatedDebitMemo = await
zuoraClient.debitMemos.patchDebitMemo(debitMemoPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
example:
id: 8ad08dc985aaee970185bd81e4024e3e
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-20T15:18:37-08:00'
created_by_id: 8ad09bce80507dab0180688bdabc20cb
created_time: '2023-01-16T18:14:44-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f96abc17de016abd62bd0c5854
description: Updated debit memo
due_date: '2023-01-20'
document_date: '2023-01-20'
reason_code: Charge Dispute
debit_memo_number: DM00000294
state_transitions: {}
state: draft
total: 10
subtotal: 10
tax: 0
remaining_balance: 10
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteDebitMemo
summary: Delete a debit memo
tags:
- Debit Memos
description: >-
Permanently deletes a debit memo. This operation cannot be undone once
it is performed.
parameters:
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/debit_memos/2c92c0f86a8dd422016a9e7a70116b0d'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.debitMemo().deleteDebitMemo(newDebitMemo.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteDebitMemoResponse = await
zuoraClient.debitMemo.deleteDebitMemo('8ad087e284427311018447079d9e4efe');
console.log(deleteDebitMemoResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos:
get:
operationId: getDebitMemoes
summary: List debit memos
tags:
- Debit Memos
description: >-
Returns a dictionary with a data property that contains an array of
debit memoes, starting after cursor. Each entry in the array is a
separate invoice object. If no more invoices are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl -X GET "https://rest.sandbox.na.zuora.com/v2/debit_memo"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
DebitMemoListResponse debitMemoListResponse =
zuoraClient.debitmemo().getDebitMemoes(null,Collections.singletonList("account"),null);
System.out.println(debitMemoListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemoListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createDebitMemo
summary: Create a debit memo
tags:
- Debit Memos
description: Creates debit memo
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemoCreateRequest'
example:
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2022-08-26'
description: test debit memo from invoice
post: true
invoice_id: 8ad09b7d82d9662c0182daeaa9f4477e
items:
- amount: 1
invoice_item_id: 8ad09b7d82d9662c0182daeaaa114781
sku: SKU-00011672
service_start: '2022-07-26'
taxation_items:
- source_tax_item_id: 8ad09b7d82d9662c0182daeaaa174784
name: taxbf3049ff
amount: 0.5
tax_code_name: tax1
tax_date: '2022-08-26'
tax_rate_name: rate1
tax_rate: 0.5
tax_inclusive: false
tax_rate_type: amount
tax_code: Maintenance Charges
- name: tax0896ba54
source_tax_item_id: 8ad09b7d82d9662c0182daeaaa174783
amount: 1
tax_code_name: tax2
tax_date: '2022-08-26'
tax_rate_name: rate2
tax_rate: 10
tax_inclusive: false
tax_rate_type: percent
tax_code: Maintenance Charges
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memo --header
'Authorization: Bearer 7676db88e1a84293a6298c8d44cc141c'
--header 'Content-Type: application/json' --data '{
"account_id": "2c92c0f96abc17de016abd62bd0c5854",
"description": "debit memo from price",
"document_date": "2022-09-01",
"reason_code": "Ad hoc credit",
"items": [
{
"price_id": "8ad0887182afa5d00182b017730c5fcb",
"amount": 10,
"quantity": 5,
"description": "item description",
"service_start": "2022-09-01"
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
DebitMemoItemCreateRequest debitMemoItemRequest = new
DebitMemoItemCreateRequest()
.amount(new BigDecimal(10.25))
.subscriptionItemName("subscription item 1")
.description("a new debit memo item")
.quantity(new BigDecimal(2))
.serviceEnd("2023-09-01")
.serviceStart("2022-09-01");
DebitMemoCreateRequest debitMemoRequest = new
DebitMemoCreateRequest()
.accountId("8ad09c4b8262e38101826441928c1162")
.pay(false)
.description("new debit memo")
.documentDate(todayDate)
.post(false)
.items(Collections.singletonList(debitMemoItemRequest));
DebitMemo newDebitMemo=
zuoraClient.debitMemo().createDebitMemo(debitMemoRequest);
- lang: JavaScript
label: Node
source: >-
const debitMemoRequest = {
"account_id": "2c92c0f96abc17de016abd62bd0c5854",
"description": "debit memo from price",
"document_date": "2022-09-01",
"reason_code": "Ad hoc credit",
"items": [
{
"price_id": "8ad0887182afa5d00182b017730c5fcb",
"amount": 10,
"quantity": 5,
"description": "item description",
"service_start": "2022-09-01"
}
]
};
const newDebitMemo = await
zuoraClient.debitmemo.createDebitMemo(debitMemoRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:56:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-02-16T12:10:28-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
description: comments
due_date: '2020-03-02'
document_date: '2020-02-01'
reason_code: Correcting invoice error
debit_memo_number: DM00000249
state_transitions:
posted: '2022-08-15T12:37:06-07:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: open
total: 300
subtotal: 300
tax: 0
balance: 290
paid: false
past_due: true
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos/{debit_memo_id}/cancel:
post:
operationId: cancelDebitMemo
summary: Cancel a debit memo
tags:
- Debit Memos
description: >-
Cancels a debit memo. Only the debit memos with the `draft` status can
be canceled.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memos/DM00000288/cancel
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data
'{}'
- lang: Java
label: Java
source: >2-
DebitMemo cancelledDebitMemo =
zuoraClient.debitMemo().cancelDebitMemo("DM00000288", null);
- lang: JavaScript
label: Node
source: >2-
const cancelledDebitMemo = await
zuoraClient.debitmemo.cancelDebitMemo("DM00000288");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memo_items:
get:
operationId: getDebitMemoItems
summary: List debit memo items
tags:
- Debit Memos
description: Lists item information on all or a subset of debit memos.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: debit_memo_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl -X GET "https://rest.sandbox.na.zuora.com/v2/debit_memo_items"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: |2-
DebitMemoItemListResponse debitMemoItemListResponse = zuoraClient.debitMemoItems().getDebitMemoItems(null, null, null);
System.out.println(debitMemoItemListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemoItemListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos/{debit_memo_id}/post:
post:
operationId: postsDebitMemo
summary: Post a debit memo
tags:
- Debit Memos
description: Opens a draft debit memo.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memos/DM00000302/post
--header 'Authorization: Bearer d1daf29d65a3476b8508a40587ef0cde'
--header 'Content-Type: application/json' --data '{}'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos/{debit_memo_id}/unpost:
post:
operationId: unpostsDebitMemo
summary: Unpost a debit memo
tags:
- Debit Memos
description: >-
Unposts an open debit memo that has not been applied or refunded, and
changes its `state` to `draft`.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: unpost
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memos/DM00000302/post
--header 'Authorization: Bearer d1daf29d65a3476b8508a40587ef0cde'
--header 'Content-Type: application/json' --data '{}'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/debit_memos/{debit_memo_id}/pay:
post:
operationId: payDebitMemo
summary: Pay a debit memo
tags:
- Debit Memos
description: Pays a debit memo using an existing payment method.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/payDebitMemoRequest'
example:
amount: 22
currency: USD
payment_date: '2023-01-31'
account_id: 2c92c0f96abc17de016abd62bd0c5854
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
gateway_id: 2c92c0f86a8dd422016a941ee0d82c7f
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `balance`, `due_date`, `debit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `posted_by_id`, `state`, `reason_code`, `paid`, `past_due`, `billing_document_settings`, `payment_terms`, `bill_to_id`, `invoice_id`, `currency`
</details>
- in: query
name: debit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `document_item_date`, `invoice_item_id`, `sku`, `name`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `subtotal`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `debit_memo_id`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: debit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the debit_memo_id, either `debit_memo_number` or
`debit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: pay
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memos/8ad09c4b84e185210184e433cb4919c1/pay
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data
'{
"amount": 22,
"currency": "USD",
"payment_date": "2023-01-31",
"account_id": "2c92c0f96abc17de016abd62bd0c5854",
"payment_method_id": "8ad08ccf8292a2d20182a95408ac6530",
"gateway_id": "2c92c0f86a8dd422016a941ee0d82c7f"
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
DebitMemoPayRequest payDebitMemoRequest = new DebitMemoPayRequest()
.amount(22)
.accountId("8ad09c4b8262e38101826441928c1162")
.paymentDate(todayDate)
.paymentMethodId("8ad08ccf8292a2d20182a95408ac6530")
.gatewayId("2c92c0f86a8dd422016a941ee0d82c7f");
DebitMemo payDebitMemo =
zuoraClient.debitmemo().payDebitMemo(payDebitMemoRequest);
- lang: JavaScript
label: Node
source: >2-
const payDebitMemoRequest = {
amount: 22,
currency: "USD",
payment_date: "2023-01-31",
account_id: "2c92c0f96abc17de016abd62bd0c5854",
payment_method_id: "8ad08ccf8292a2d20182a95408ac6530",
gateway_id: "2c92c0f86a8dd422016a941ee0d82c7f",
};
const payDebitMemo = await
zuoraClient.debitmemo.payDebitMemo("debitMemoPayRequest");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/debitMemo'
example:
id: 8ad08dc986023f76018608da69e8606a
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-31T09:22:57-08:00'
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-31T09:22:57-08:00'
payment_number: P-00002779
payment_date: '2023-01-31'
gateway_id: Test Gateway
payment_method_id: 8ad08ccf8292a2d20182a95408ac6530
reference_id: '6168540.740581938'
state: posted
account_id: 2c92c0f96abc17de016abd62bd0c5854
amount: 22
amount_applied: 22
amount_refunded: 0
remaining_balance: 0
currency: USD
external: false
gateway_response: This transaction has been approved by Test gateway.
gateway_response_code: approve
gateway_state: submitted
custom_fields:
field__c: custom field value
state_transitions: {}
gateway_state_transitions:
submitted_time: '2023-01-31T09:22:57-08:00'
custom_objects: {}
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}:
get:
operationId: getCreditMemo
summary: Retrieve a credit memo
tags:
- Credit Memos
description: Retrieves the credit memo with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/credit_memos/8ad0855180f9da510180fbf80db40c79"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
CreditMemo creditMemoResponse =
zuoraClient.creditMemos().getCreditMemo(newCreditMemo.getId(),null,null);
System.out.println(creditMemoResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchCreditMemo
summary: Update a credit memo
tags:
- Credit Memos
description: >-
Updates a credit memo by setting the values of the specified fields. Any
fields not provided in the request remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemoPatchRequest'
example:
description: Updated credit memo
document_date: '2023-01-16'
reason_code: Charge Dispute
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
'https://rest.apisandbox.zuora.com/v2/credit_memos/8ad08c84858672100185a2662c381b35?='
--header 'Authorization: Bearer
50c3e24363864c96af0742adebd9a788' --header 'Content-Type:
application/json' --header 'x-donut-auth: Bearer
50c3e24363864c96af0742adebd9a788' --data '{
"description": "Updated credit memo",
"document_date": "2023-01-16",
"reason_code": "Charge Dispute"
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
CreditMemoPatchRequest creditMemoPatchRequest = new
CreditMemoPatchRequest()
.description("Updated credit memo")
.documentDate(todayDate)
.reasonCode("Charge Dispute");
CreditMemo updatedCreditMemo =
zuoraClient.creditMemos().patchCreditMemo(creditMemoPatchRequest);
- lang: JavaScript
label: Node
source: >-
const creditMemoPatchRequest = {
description: "Updated credit memo",
document_date: "2023-01-16",
reason_code: "Charge Dispute"
};
const updatedCreditMemo = await
zuoraClient.creditMemos.patchCreditMemo(creditMemoPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad08c84858672100185a2662c381b35
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-19T16:13:05-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-11T11:54:43-08:00'
custom_fields:
EmailSentWorkflow__c: Unprocessed
account_id: 8ad0823f8455bb400184633077e63aaf
description: Updated credit memo
document_date: '2023-01-16'
reason_code: Charge Dispute
invoice_id: 8ad0889d8586720901859756c62f2959
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000658
amount_refunded: 0
state_transitions: {}
state: draft
total: 2545.65
subtotal: 2545.65
tax: 0
remaining_balance: 2545.65
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteCreditMemo
summary: Delete a credit memo
tags:
- Credit Memos
description: >-
Permanently deletes a credit memo. This operation cannot be undone once
it is performed.
parameters:
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/credit_memos/2c92c0f86a8dd422016a9e7a70116b0d'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.creditMemo().deleteCreditMemo(newCreditMemo.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteCreditMemoResponse = await
zuoraClient.creditMemo.deleteCreditMemo('8ad087e284427311018447079d9e4efe');
console.log(deleteCreditMemoResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos:
get:
operationId: getCreditMemos
summary: List credit memos
tags:
- Credit Memos
description: >-
Returns a dictionary with a data property that contains an array of
credit memos, starting after cursor. Each entry in the array is a
separate credit memo object. If no more credit memos are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: |2-
curl -X GET "https://rest.sandbox.na.zuora.com/v2/credit_memos"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
CreditMemoListResponse creditMemoListResponse =
zuoraClient.creditMemos().getCreditMemos(null,Collections.singletonList("account"),null);
System.out.println(creditMemoListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemoListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2021-12-09T13:07:18-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2021-12-09T13:07:18-08:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f86a8dd422016a9e7a70116b0d
document_date: '2021-12-09'
reason_code: Write-off
invoice_id: 8ad08aff7aeb7334017aec634dce2ec2
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000415
amount_refunded: 0
state_transitions:
posted_at: '2021-12-09T13:07:18-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 31699.88
subtotal: 31274.4
tax: 425.48
remaining_balance: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createCreditMemo
summary: Create a credit memo
tags:
- Credit Memos
description: Creates a new credit memo.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemoCreateRequest'
example:
account_id: 8ad08ccf8437067601843a7af4e75ac8
description: new credit memo
document_date: '2022-11-21'
invoice_id: 8ad0950c8455ccf901846413677a40f9
reason_code: Charge Dispute
items:
- invoice_item_id: 8ad0950c8455ccf901846413679a40fa
amount: 100
service_start: '2022-11-04'
service_end: '2023-02-01'
name: Music Stream Plus
description: A new credit memo item
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/credit_memos --header
'Authorization: Bearer 7676db88e1a84293a6298c8d44cc141c'
--header 'Content-Type: application/json' --data '{
"account_id": "8ad08ccf806f42ed018090759555446b",
"description": "new credit memo",
"document_date": "2022-11-21",
"invoice_id":"8ad0950c8455ccf901846413677a40f9",
"reason_code": "Charge Dispute",
"items": [
{
"invoice_item_id": "8ad0950c8455ccf901846413679a40fa",
"amount": 100,
"service_start": "2022-11-04",
"service_end": "2023-02-01",
"name": "Music Stream Plus",
"description":"A new credit memo item",
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
CreditMemoItemCreateRequest creditMemoItemRequest = new
CreditMemoItemCreateRequest()
.amount(new BigDecimal(100))
.invoiceItemId("8ad0950c8455ccf901846413679a40fa")
.name("Music Stream Plus")
.description("A new credit memo item")
.serviceEnd("2023-02-01")
.serviceStart("2022-11-04");
CreditMemoCreateRequest creditMemoRequest = new
CreditMemoCreateRequest()
.accountId("8ad08ccf806f42ed018090759555446b")
.description("new credit memo")
.documentDate(todayDate)
.invoiceId("8ad0950c8455ccf901846413677a40f9")
.reasonCode("Charge Dispute")
.items(Collections.singletonList(creditMemoItemRequest));
CreditMemo newCreditMemo =
zuoraClient.creditMemos().createCreditMemo(creditMemoRequest);
- lang: JavaScript
label: Node
source: "\nconst creditMemoRequest = {\n account_id: \"8ad08ccf806f42ed018090759555446b\",\n description: \"new credit memo\",\n document_date: \"2022-11-21\",\n invoice_id: \"8ad0950c8455ccf901846413677a40f9\",\n reason_code: \"Charge Dispute\",\n items: [{\n invoice_item_id: \"8ad0950c8455ccf901846413679a40fa\",\t\n amount: 100,\n service_start: \"2022-11-04\",\n service_end: \"2023-02-01\",\n name : \"Music Stream Plus\",\n description: \"a new credit memo item\",\n }]\n};\n \nconst newCreditMemo = await zuoraClient.creditMemos.createCreditMemo(creditMemoRequest);\n "
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad0855184d191a70184d4ccc64079c5
credit_memo_number: CM00000600
account_id: 8ad08ccf8437067601843a7af4e75ac8
created_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-12-02T13:45:00-08:00'
updated_time: '2022-12-02T13:45:00-08:00'
exclude_from_auto_apply_rules: false
state_transitions: {}
state: draft
invoice_id: 8ad0950c8455ccf901846413677a40f9
description: new credit memo
reason_code: Charge Dispute
remaining_balance: 100
total: 100
subtotal: 100
tax: 0
document_date: '2022-11-21'
amount_refunded: 0
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memo_items:
get:
operationId: getCreditMemoItems
summary: List credit memo items
tags:
- Credit Memos
description: >-
Retrieves information about all items of credit memos. A credit memo
item is a single line item in a credit memo.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/credit_memo_items"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
CreditMemoItemListResponse creditMemoItemListResponse =
zuoraClient.creditMemos().getCreditMemoItems(null, null, null);
System.out.println(creditMemoItemListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemoItemListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}/apply:
post:
operationId: applyCreditMemo
summary: Apply a credit memo
tags:
- Credit Memos
description: Apply a credit memo to one or more other billing documents.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/applyUnapplyCreditMemo'
example:
effective_date: '2022-12-15'
billing_documents:
- type: invoice
id: 8ad09e2085cf16230185cfc951f743fc
amount: 2
items:
- credit_memo_item_id: 8ad0934e85d31edf0185e0120a122ae8
amount: 2
id: 8ad09e2085cf16230185cfc9521f43fd
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: apply
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/credit_memos/8ad0855184eab9e10184f25604c91287/apply
--header 'Authorization: Bearer
7676db88e1a84293a6298c8d44cc141c' --header 'Content-Type:
application/json' --data '{
"effective_date": "2022-12-15",
"billing_documents": [
{
"type": "invoice",
"id": "8ad0950c8455ccf901846413677a40f9",
"amount": 50
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
BillingDocumentApplicationRequest billingDocumentApplicationRequest
= new BillingDocumentApplicationRequest()
.type(BillingDocumentApplicationRequest.TypeEnum.INVOICE)
.id("8ad0950c8455ccf901846413677a40f9")
.amount(new BigDecimal(50));
ApplyCreditMemo applyCreditMemo = new ApplyCreditMemo()
.effectiveDate(todayDate)
.billingDocuments(Collections.singletonList(billingDocumentApplicationRequest));
CreditMemo creditMemo =
zuoraClient.creditMemos().applyCreditMemo(applyCreditMemo);
- lang: JavaScript
label: Node
source: >-
const creditMemoApplyRequest = {
"effective_date": "2022-12-15",
"billing_documents": [
{
"type": "invoice",
"id": "8ad0950c8455ccf901846413677a40f9",
"amount": 50
}
]
};
const creditMemo = await
zuoraClient.creditMemos.applyCreditMemo(creditMemoApplyRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad0934e85d31edf0185e0120a052ae5
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-24T07:06:32-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-23T11:19:16-08:00'
account_id: 2c92c0f96abc17de016abd62bd0c5854
description: test debit memo from invoice
document_date: '2022-08-26'
reason_code: Ad hoc credit
invoice_id: 8ad09e2085cf16230185cfc951f743fc
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000675
amount_refunded: 0
state_transitions:
posted_at: '2023-01-23T11:19:16-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 9
subtotal: 9
tax: 0
remaining_balance: 5
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}/unapply:
post:
operationId: unapplyCreditMemo
summary: Unapply a credit memo
tags:
- Credit Memos
description: Unapply an applied credit memo.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/applyUnapplyCreditMemo'
example:
effective_date: '2022-12-15'
billing_documents:
- type: debit_memo
id: 8ad0855184eab9e10184ed05d9992c9a
amount: 5
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: unapply
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/credit_memos/8ad0855184eab9e10184f25604c91287/unapply
--header 'Authorization: Bearer
7676db88e1a84293a6298c8d44cc141c' --header 'Content-Type:
application/json' --data '{
"effective_date": "2022-12-15",
"billing_documents": [
{
"type": "invoice",
"id": "8ad0950c8455ccf901846413677a40f9",
"amount": 50
}
]
}'
- lang: Java
label: Java
source: >2-
LocalDate todayDate = LocalDate.now();
BillingDocumentApplicationRequest billingDocumentApplicationRequest
= new BillingDocumentApplicationRequest()
.type(BillingDocumentApplicationRequest.TypeEnum.INVOICE)
.id("8ad0950c8455ccf901846413677a40f9")
.amount(new BigDecimal(50));
UnapplyCreditMemo unapplyCreditMemo = new UnapplyCreditMemo()
.effectiveDate(todayDate)
.billingDocuments(Collections.singletonList(billingDocumentApplicationRequest));
CreditMemo creditMemo =
zuoraClient.creditMemos().unapplyCreditMemo(unapplyCreditMemo);
- lang: JavaScript
label: Node
source: >-
const creditMemoUnapplyRequest = {
"effective_date": "2022-12-15",
"billing_documents": [
{
"type": "invoice",
"id": "8ad0950c8455ccf901846413677a40f9",
"amount": 50
}
]
};
const creditMemo = await
zuoraClient.creditMemos.unapplyCreditMemo(creditMemoUnapplyRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
example:
id: 8ad08551844271830184443647f96987
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2022-12-12T10:01:09-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2022-11-04T12:55:18-07:00'
custom_fields:
field__c: custom field value
account_id: 2c92c0f96abc17de016abd62bd0c5854
description: credit memo from price
document_date: '2022-09-01'
reason_code: Correcting invoice error
exclude_from_auto_apply_rules: false
credit_memo_number: CM00000508
amount_refunded: 0
state_transitions:
posted_at: '2022-12-08T12:07:55-08:00'
posted_by_id: 2c92c0946a6dffc0016a7faab604299b
state: draft
total: 10
subtotal: 10
tax: 0
remaining_balance: 5
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}/unpost:
post:
operationId: unpostCreditMemo
summary: Unpost a credit memo
tags:
- Credit Memos
description: >-
Unposts an open credit memo that has not been applied, and changes its
`state` to `draft`.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: unpost
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/credit_memos/8ad09e2085ab06ac0185bd7fbfc308f2/unpost
--header 'Authorization: Bearer
787c70adc7214cd88e3dcd218ae2eee2' --header 'Content-Type:
application/json' --data '{}'
- lang: Java
label: Java
source: >-
CreditMemo creditMemoResponse =
zuoraClient.creditMemos().unpostCreditMemo(newCreditMemo.getId(),null,null);
System.out.println(creditMemoResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}/post:
post:
operationId: postCreditMemo
summary: Post a credit memo
tags:
- Credit Memos
description: Opens a draft credit memo.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >
curl -X GET
"https://rest.sandbox.na.zuora.com/v2/credit_memos/8ad0855180f9da510180fbf80db40c79/post"
-H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3"
-H "Content-Type: application/json"
- lang: Java
label: Java
source: >-
CreditMemo creditMemoResponse =
zuoraClient.creditMemos().postCreditMemo(newCreditMemo.getId(),null,null);
System.out.println(creditMemoResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/credit_memos/{credit_memo_id}/cancel:
post:
operationId: cancelCreditMemo
summary: Cancel a credit memo
tags:
- Credit Memos
description: >-
Cancels a credit memo. Only credit memos with the Draft status can be
cancelled.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: credit_memo.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `credit_memo_number`, `state_transitions`, `description`, `account_id`, `total`, `subtotal`, `tax`, `document_date`, `exclude_from_auto_apply_rules`, `posted_by_id`, `state`, `balance`, `invoice_id`, `reason_code`, `amount_refunded`, `bill_to_id`, `billing_document_settings`, `currency`
</details>
- in: query
name: applied_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`id`, `amount`, `billing_document_id`, `billing_document_type`
</details>
- in: query
name: credit_memo_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: taxation_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `source_tax_item_id`, `amount_applied`, `amount_refunded`, `on_account_account`
</details>
- in: query
name: account.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled`
</details>
- in: query
name: bill_to.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: credit_memo_id
required: true
schema:
type: string
description: >-
Identifier for the credit memo, either `credit_memo_number` or
`credit_memo_id`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: cancel
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/debit_memos/CM00000288/cancel
--header 'Content-Type: application/json' --header
'x-donut-auth: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data
'{}'
- lang: Java
label: Java
source: >2-
CreditMemo cancelledCreditMemo =
zuoraClient.creditMemo().cancelCreditMemo("CM00000288", null);
- lang: JavaScript
label: Node
source: >2-
const cancelledCreditMemo = await
zuoraClient.creditMemo.cancelCreditMemo("CM00000288");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/creditMemo'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/taxation_items:
get:
operationId: getTaxationItems
summary: List taxation items
tags:
- Taxation Items
description: >-
Returns an array of taxation items. Each entry in the array is a
separate Taxation Item object. If no more taxation items are available,
the resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: taxation_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/taxation_items' --header
'Authorization: Bearer d8a7f4d2a5ef4c3eba8618cf99593e26'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
ListTaxationItemResponse taxationItemListResponse =
zuoraClient.taxationItems().getTaxationItems(null,null);
System.out.println(taxationItemListResponse);
- lang: JavaScript
label: Node
source: >-
const taxationItemsResponse = await
zuoraClient.taxationItems.getTaxationItems({
filter: [
'id.EQ:d8a7f4d2a5ef4c3eba8618cf99593e26',
],
})
console.log(taxationItemsResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItemListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createTaxationItem
summary: Create a taxation item
tags:
- Taxation Items
description: Creates a taxation item.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItemCreateRequest'
example:
name: tax
amount: 12
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
amount_exempt: 2
tax_inclusive: false
invoice_item_id: 8ad086ec85a701ce0185a782b1db3b74
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: taxation_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/taxation_items --header
'Authorization: Bearer 8d17d8e8cc36419998a205896d670ed2'
--header 'Content-Type: application/json' --data '{
"name": "tax",
"amount": 12,
"tax_code": "Maintenance Charges",
"tax_code_name": "",
"tax_date": "2022-01-12",
"tax_rate": 1,
"tax_rate_name": "",
"amount_exempt": 2,
"tax_inclusive": false,
"invoice_item_id":"8ad086ec85a701ce0185a782b1db3b74"
}'
- lang: Java
label: Java
source: |2-
TaxationItemCreateRequest taxationItemCreateRequest = new TaxationItemCreateRequest()
.tax_date("2022-01-12")
.name("tax")
.amount(12)
.tax_code("Maintenance Charges")
.tax_rate(2)
TaxationItem newTaxationItem = zuoraClient.taxationItems().createTaxationItem(taxationItemCreateRequest);
- lang: JavaScript
label: Node
source: |2-
const taxationItemCreateRequest = {
"name": "tax",
"amount": 12,
"tax_code": "Maintenance Charges",
"tax_code_name": "",
"tax_date": "2022-01-12",
"tax_rate": 1,
"tax_rate_name": "",
"amount_exempt": 2,
"tax_inclusive": false,
"invoice_item_id":"8ad086ec85a701ce0185a782b1db3b74"
};
const newTaxationItem = await zuoraClient.taxationItems.createTaxationItem(taxationItemCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItem'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/taxation_items/{taxation_item_id}:
get:
operationId: getTaxationItem
summary: Retrieve a taxation item
tags:
- Taxation Items
description: Retrieves the taxation item with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: taxation_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: taxation_item_id
required: true
schema:
type: string
description: ID of the taxation item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/taxation_items/8ad099158561c2b901857ecbd9131422
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
TaxationItem taxationItemResponse =
zuoraClient.taxationItems().getTaxationItem(newTaxationItem.getId(),null);
System.out.println(taxationItemResponse);
- lang: JavaScript
label: Node
source: >-
const taxationItemResponse = await
zuoraClient.taxationItems.getTaxationItem('8ad099158561c2b901857ecbd9131422');
console.log(taxationItemResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItem'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: County Charge
amount: 0
tax_code: Maintenance Charges
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateTaxationItem
summary: Update a taxation item
tags:
- Taxation Items
description: >-
Updates a taxation item by setting the values of the specified fields.
Any fields not provided in the request remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItemPatchRequest'
example:
tax_code_name: Forsyth
name: Forsyth Charge
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: taxation_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `amount_exempt`, `tax_date`, `jurisdiction`, `location_code`, `name`, `sales_tax_payable_account`, `tax_code`, `tax_code_name`, `tax_rate`, `tax_rate_name`, `tax_inclusive`, `tax_rate_type`, `amount_credited`, `amount_paid`, `remaining_balance`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: taxation_item_id
required: true
schema:
type: string
description: ID of the taxation item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/taxation_items/8ad086ec85a701ce0185a782adb13b62
--header 'Authorization: Bearer
06a297740b184fc384bc57cbe8a04e53' --header 'Content-Type:
application/json' --data '{
"location_code": "30328",
"name": "County Charge",
"tax_rate": 1,
"tax_rate_name": "County"
}'
- lang: Java
label: Java
source: >-
TaxationItem oldTaxationItem =
zuoraClient.taxationItems().getTaxationItems("8ad086ec85a701ce0185a782adb13b62",
null);
TaxationItemPatchRequest taxationItemPatchRequest = new
TaxationItemPatchRequest()
.name("County Charge");
TaxationItem updatedTaxationItem =
zuoraClient.taxationItems().updateTaxationItem(oldTaxationItem.getId(),taxationItemPatchRequest);
- lang: JavaScript
label: Node
source: >-
const taxationItemPatchRequest = {
"name": "County Charge",
};
const updatedTaxationItem = await
zuoraClient.taxationItems.updateTaxationItem('8ad086ec85a701ce0185a782adb13b62',
taxationItemPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/taxationItem'
example:
id: 8ad086ec85a701ce0185a782adb13b62
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-01-18T10:21:27-08:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-01-12T11:43:57-08:00'
custom_fields: {}
jurisdiction: Forsyth
location_code: '123'
name: Forsyth Charge
amount: 0
tax_code: Maintenance Charges
tax_code_name: Forsyth
tax_date: '2022-01-12'
tax_rate: 1
tax_rate_name: Charge
amount_exempt: 0
remaining_balance: 0
amount_credited: 0
amount_paid: 0
tax_inclusive: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteTaxationItem
summary: Delete a taxation item
tags:
- Taxation Items
description: >-
Permanently deletes a taxation item. This operation cannot be undone
once it is performed.
parameters:
- in: path
name: taxation_item_id
required: true
schema:
type: string
description: ID of the taxation item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/taxation_items/2c92c0f86a8dd422016a9e7a70116b0d'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.taxationItems().deleteTaxationItem(newTaxationItem.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deleteTaxationItemResponse = await
zuoraClient.taxationItems.deleteTaxationItem('8ad087e284427311018447079d9e4efe');
console.log(deleteTaxationItemResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_runs:
get:
operationId: getPaymentRuns
summary: List payment runs
tags:
- Payment Runs
description: >-
Returns an array of payment runs. Each entry in the array is a separate
payment run object. If no more payment runs are available, the
resulting array will be empty. This request should never return an
error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: payment_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: summary.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `number_of_unprocessed_receivables`, `number_of_errors`, `number_of_invoices`, `number_of_payments`, `number_of_credit_memos`, `number_of_debit_memos`, `number_of_unprocessed_debit_memos`, `number_of_unapplied_payments`, `errors_total`, `invoices_total`, `payments_total`, `unprocessed_receivables_total`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/payment_runs --header
'Authorization: Bearer dcf5d050c6e7493688859d04da581938'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
PaymentRunListResponse paymentRunListResponse =
zuoraClient.paymentRuns().getPaymentRuns(null,null,null);
System.out.println(paymentRunListResponse);
- lang: JavaScript
label: Node
source: >-
const paymentRunListResponse = await
zuoraClient.paymentRuns.getPaymentRuns({
filter: [
'state.EQ:completed',
]
});
console.log(paymentRunListResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRunListResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createPaymentRuns
summary: Create a payment run
tags:
- Payment Runs
description: >-
Creates a payment run.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentRunCreateRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: payment_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: summary.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `number_of_unprocessed_receivables`, `number_of_errors`, `number_of_invoices`, `number_of_payments`, `number_of_credit_memos`, `number_of_debit_memos`, `number_of_unprocessed_debit_memos`, `number_of_unapplied_payments`, `errors_total`, `invoices_total`, `payments_total`, `unprocessed_receivables_total`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_runs --header
'Content-Type: application/json' --header 'x-donut-auth: Bearer
4f3a8ca735f54e9e8ea118c086dc34e1' --data '{
"target_date": "2023-02-10",
"batch": "Batch1",
"gateway_id": "8ad0938485cf16810185d00bf7294ec4"
}'
- lang: Java
label: Java
source: >-
LocalDate todayDate = LocalDate.now();
PaymentRunCreateRequest paymentRunCreateRequest = new
PaymentRunCreateRequest()
.gateway_id("8ad0938485cf16810185d00bf7294ec4")
.batch("Batch1"),
.targetDate(todayDate);
PaymentRun newPaymentRun =
zuoraClient.paymentRuns().createPaymentRun(paymentRunCreateRequest);
- lang: JavaScript
label: Node
source: >-
const paymentRunCreateRequest = {
gateway_id: 8ad0938485cf16810185d00bf7294ec4,
batch: "Batch1",
target_date: "2022-01-12"
};
const newPaymentRun = await
zuoraClient.paymentRuns.createPaymentRun(paymentRunCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentRun'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_runs/{payment_run_id}:
get:
operationId: getPaymentRun
summary: Retrieve a payment run
tags:
- Payment Runs
description: Retrieves the payment run information with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: payment_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: summary.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `number_of_unprocessed_receivables`, `number_of_errors`, `number_of_invoices`, `number_of_payments`, `number_of_credit_memos`, `number_of_debit_memos`, `number_of_unprocessed_debit_memos`, `number_of_unapplied_payments`, `errors_total`, `invoices_total`, `payments_total`, `unprocessed_receivables_total`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_run_id
required: true
schema:
type: string
description: >-
Identifier for the payment run, either `payment_run_number` or
`payment_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/payment_runs/8ad08c8485a701b30185a782a30a6c88
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
PaymentRun paymentRunResponse =
zuoraClient.paymentRuns().getPaymentRun(newPaymentRun.getId(),null);
System.out.println(paymentRun);
- lang: JavaScript
label: Node
source: >-
const paymentRunResponse = await
zuoraClient.paymentRuns.getPaymentRun('8ad08c8485a701b30185a782a30a6c88');
console.log(paymentRunResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentRun'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePaymentRuns
summary: Update a payment run
tags:
- Payment Runs
description: >-
Updates a payment run by setting the values of the specified fields. Any
fields not provided in the request remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentRunPatchRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: payment_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `batch`, `bill_cycle_day`, `target_date`, `payment_run_number`, `state`, `apply_credit_memos`, `apply_unapplied_payments`, `bill_run_id`, `collect_payment`, `consolidate_payment`, `payment_run_date`, `payment_gateway_id`, `state_transitions`
</details>
- in: query
name: summary.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `number_of_unprocessed_receivables`, `number_of_errors`, `number_of_invoices`, `number_of_payments`, `number_of_credit_memos`, `number_of_debit_memos`, `number_of_unprocessed_debit_memos`, `number_of_unapplied_payments`, `errors_total`, `invoices_total`, `payments_total`, `unprocessed_receivables_total`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_run_id
required: true
schema:
type: string
description: >-
Identifier for the payment run, either `payment_run_number` or
`payment_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/payment_runs/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"target_date": "2023-02-10",
"batch": "Batch1",
}'
- lang: Java
label: Java
source: >-
PaymentRun oldPaymentRun =
zuoraClient.paymentRuns().getPaymentRun("8ad0991582aa848e0182ae9dad214dd0");
PaymentRunPatchRequest paymentRunPatchRequest = new
PaymentRunPatchRequest()
.batch("Batch1"),
.targetDate(todayDate);
PaymentRun updatedPaymentRun =
zuoraClient.paymentRun().updatePaymentRun(oldPaymentRun.getId(),paymentRunPatchRequest);
- lang: JavaScript
label: Node
source: >-
const paymentRunId = newPaymentRun.id;
const paymentRunPatchRequest = {
target_date: '2023-02-10',
batch: 'Batch1',
};
const updatedPaymentRun = await
zuoraClient.paymentRuns.updatePaymentRun(paymentRunId,
paymentRunPatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentRun'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deletePaymentRuns
summary: Delete a payment run
tags:
- Payment Runs
description: >-
Deletes a payment run. Only the payment runs with the `canceled` or
`pending` status can be deleted.
parameters:
- in: path
name: payment_run_id
required: true
schema:
type: string
description: >-
Identifier for the payment run, either `payment_run_number` or
`payment_run_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/payment_runs/8f64d4d7fa661677e277dcb1ef8ee8de'
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.paymentRuns().deletePaymentRun(newPaymentRun.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const deletePaymentRunResponse = await
zuoraClient.PaymentRuns.deletePaymentRun('8f64d4d7fa661677e277dcb1ef8ee8de');
console.log(deletePaymentRunResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/order_line_items/{order_line_item_id}:
get:
operationId: getOrderLineItem
summary: Retrieve an order line item
tags:
- Order Line Items
description: >-
Use this operation to retrieve the detailed information about a specific
order line item.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: order_line_item_id
required: true
schema:
type: string
description: Identifier for the order line item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/order_line_items/8ad09b218736ff1b018749258bf15f73?='
--header 'Authorization: Bearer
9e548fc38ecd4787aa9810cb8505aacc' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >2-
OrderLineItem orderLineItem =
zuoraClient.orderLineItems().getOrderLineItem("8ad09b218736ff1b018749258bf15f73");
System.out.println(orderLineItem);
- lang: JavaScript
label: Node
source: >-
const orderLineItem = await
zuoraClient.orderLineItems.getOrderLineItem('8ad09b218736ff1b018749258bf15f73');
console.log(orderLineItem);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/orderLineItem'
example:
id: 8ad09b218736ff1b018749258bf15f73
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-03T16:03:39-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-03T15:03:30-07:00'
custom_fields: {}
unit_of_measure: Each
accounting_code: ''
adjustment_liability_account: ''
adjustment_revenue_account: ''
unit_amount: 1100
target_date: '2023-02-15'
deferred_revenue_account: ''
description: ''
discount_unit_amount: -100
name: A cellphone
type: product
list_unit_price: 1000
product_code: aapl_14_pro
purchase_order_number: ''
quantity: 40
recognized_revenue_account: ''
related_subscription_number: ''
revenue_recognition_rule_name: ''
sold_to_id: 8ad09b218736ff1b018749258b9a5f70
tax_code: ''
unbilled_receivables_account: ''
revenue:
adjustment_revenue_account: null
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
item_number: '1'
category: sale
state: pending
price_id: ''
quantity_available_for_return: 0
tax_inclusive: false
start_date: '2023-02-15'
end_date: '2023-02-15'
order_id: 8ad09b218736ff1b018749258a265f3d
total: 44000
subtotal: 44000
quantity_fulfilled: 0
quantity_pending_fulfillment: 40
original_order_date: '2023-02-15'
discount_total: -4000
list_price: 40000
original_sold_to_id: 8ad09e208727f63f018734233f6d39c2
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: patchOrderLineItem
summary: Update an order line item
tags:
- Order Line Items
description: >-
Use this operation to update the information of a specific order line
item.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/lineItemPatchRequest'
example:
name: A cellphone
type: product
quantity: 40
list_unit_price: 1000
product_code: aapl_14_pro
unit_amount: 1100
unit_of_measure: Each
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: line_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
</details>
- in: query
name: invoice_items.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: order_line_item_id
required: true
schema:
type: string
description: Identifier for the order line item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
'https://rest.apisandbox.zuora.com/v2/order_line_items/8ad09b218736ff1b018749258bf15f73?='
--header 'Authorization: Bearer
9e548fc38ecd4787aa9810cb8505aacc' --header 'Content-Type:
application/json' --data '{
"name": "A cellphone",
"type": "product",
"quantity": 40,
"list_unit_price": 1000,
"product_code": "aapl_14_pro",
"unit_amount": 1100,
"unit_of_measure": "Each"
}'
- lang: Java
label: Java
source: >2-
OrderLineItemPatchRequest orderLineItemPatchRequest = new
OrderLineItemPatchRequest()
.name("A cellphone")
.quantity(40)
.productCode("aapl_14_pro)
.listUnitPrice(1000)
.unitAmount(1100)
.unitOfMeasure("Each");
OrderLineItem updatedOrderLineItem =
zuoraClient.orderLineItems().patchOrderLineItem("8ad09b218736ff1b018749258bf15f73",
orderLineItemPatchRequest);
System.out.println(updatedOrderLineItem);
- lang: JavaScript
label: Node
source: >-
const orderLineItemPatchRequest = {
name: "A cellphone",
type: "product",
quantity: 40,
list_unit_price: 1000,
product_code: "aapl_14_pro",
unit_amount: 1100,
unit_of_measure: "Each"
};
const updatedOrderLineItem = await
zuoraClient.orderLineItems.patchOrderLineItem('8ad09b218736ff1b018749258bf15f73',
orderLineItemPatchRequest);
console.log(updatedOrderLineItem);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/orderLineItem'
example:
id: 8ad09b218736ff1b018749258bf15f73
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-04-03T16:03:39-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-04-03T15:03:30-07:00'
custom_fields: {}
unit_of_measure: Each
accounting_code: ''
adjustment_liability_account: ''
adjustment_revenue_account: ''
unit_amount: 1100
target_date: '2023-02-15'
deferred_revenue_account: ''
description: ''
discount_unit_amount: -100
name: A cellphone
type: product
list_unit_price: 1000
product_code: aapl_14_pro
purchase_order_number: ''
quantity: 40
recognized_revenue_account: ''
related_subscription_number: ''
revenue_recognition_rule_name: ''
sold_to_id: 8ad09b218736ff1b018749258b9a5f70
tax_code: ''
unbilled_receivables_account: ''
revenue:
adjustment_revenue_account: null
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
item_number: '1'
category: sale
state: pending
price_id: ''
quantity_available_for_return: 0
tax_inclusive: false
start_date: '2023-02-15'
end_date: '2023-02-15'
order_id: 8ad09b218736ff1b018749258a265f3d
total: 44000
subtotal: 44000
quantity_fulfilled: 0
quantity_pending_fulfillment: 40
original_order_date: '2023-02-15'
discount_total: -4000
list_price: 40000
original_sold_to_id: 8ad09e208727f63f018734233f6d39c2
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_run_previews/{bill_run_preview_id}:
get:
operationId: getBillRunPreview
summary: Retrieve a bill run preview
tags:
- Bill Run Previews
description: Retrieves the bill run preview information with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `assume_renewal`, `charges_excluded`, `batches`, `target_date`, `state`, `number_of_accounts`, `number_of_accounts_succeeded`, `state_transitions`, `billing_preview_run_number`, `file`, `include_draft_items`, `include_evergreen_subscriptions`
</details>
- in: query
name: bill_run_preview.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `assume_renewal`, `charges_excluded`, `batches`, `target_date`, `state`, `number_of_accounts`, `number_of_accounts_succeeded`, `state_transitions`, `billing_preview_run_number`, `file`, `include_draft_items`, `include_evergreen_subscriptions`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: bill_run_preview_id
required: true
schema:
type: string
description: Identifier for the bill run preview.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/bill_runs/8ad08c8485a701b30185a782a30a6c88
--header 'Authorization: Bearer
dcf5d050c6e7493688859d04da581938' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
BillRunPreview billRunPreviewResponse =
zuoraClient.billRunPreviews().getBillRunPreview(newBillRunPreview.getId(),null);
System.out.println(billRunPreviewResponse);
- lang: JavaScript
label: Node
source: >-
const billRunPreviewResponse = await
zuoraClient.billRunPreviews.getBillRunPreview('8ad0934e8727f642018729728eae1b2a');
console.log(billRunPreviewResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRunPreview'
example:
id: 8ad0934e8727f642018729728eae1b2a
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28 11:19:57'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28 11:19:46'
assume_renewal: auto_renew_only
batches:
- Batch3
- Batch4
charges_excluded:
- one_time
- usage
include_draft_items: false
include_evergreen_subscriptions: true
target_date: '2023-01-01'
state_transitions:
complete_time: '2023-03-28 11:19:57'
processing_start_time: '2023-03-28 11:19:47'
file:
url: 8ad0962d8727efba01872972b9f235a5
billing_preview_run_number: BPR-00000039
state: completed
number_of_accounts_succeeded: 1
number_of_accounts: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/bill_run_previews:
post:
operationId: createBillRunPreview
summary: Create a bill run preview
tags:
- Bill Run Previews
description: Creates a bill run preview for a batch of customer accounts.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/billRunPreviewCreateRequest'
example:
include_draft_items: false
include_evergreen_subscriptions: true
charges_excluded:
- one_time
- usage
target_date: '2023-01-01'
batches:
- Batch3
- Batch4
assume_renewal: auto_renew_only
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `assume_renewal`, `charges_excluded`, `batches`, `target_date`, `state`, `number_of_accounts`, `number_of_accounts_succeeded`, `state_transitions`, `billing_preview_run_number`, `file`, `include_draft_items`, `include_evergreen_subscriptions`
</details>
- in: query
name: bill_run_preview.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `assume_renewal`, `charges_excluded`, `batches`, `target_date`, `state`, `number_of_accounts`, `number_of_accounts_succeeded`, `state_transitions`, `billing_preview_run_number`, `file`, `include_draft_items`, `include_evergreen_subscriptions`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/bill_run_previews --header
'Content-Type: application/json' --header 'Authorization:
Bearer d13fdb394bad49a596390bf54b479bc3' --data '{
"include_draft_items": false,
"include_evergreen_subscriptions": true,
"charges_excluded": ["one_time", "usage"],
"target_date": "2023-01-01",
"batches": ["Batch3", "Batch4"],
"assume_renewal": "auto_renew_only"
}'
- lang: Java
label: Java
source: >-
LocalDate todayDate = LocalDate.now();
BillRunPreviewCreateRequest billRunPreviewCreateRequest = new
BillRunPreviewCreateRequest()
.includeDraftItems(false)
.includeEvergreenSubscriptions(true)
.chargesExcluded(new ArrayList<>(Arrays.asList(
BillRunPreviewCreateRequest.ChargesExcludedEnum.ONE_TIME,
BillRunPreviewCreateRequest.ChargesExcludedEnum.USAGE)))
.targetDate(todayDate)
.batches(new ArrayList<>(Arrays.asList(
"Batch3", "Batch4"
)))
.assumeRenewal(BillRunPreviewCreateRequest.AssumeRenewalEnum.AUTO_RENEW_ONLY);
BillRunPreview billRunPreview = zuoraClient
.billRunPreviews()
.createBillRunPreview(billRunPreviewCreateRequest);
- lang: JavaScript
label: Node
source: >-
const billRunPreviewCreateRequest = {
include_draft_items: false,
include_evergreen_subscriptions: true,
charges_excluded: ["one_time", "usage"],
target_date: "2023-01-01",
batches: ["Batch3", "Batch4"],
assume_renewal: "auto_renew_only"
};
const newBillRunPreview = await
zuoraClient.billRunPreviews.createBillRunPreview(billRunPreviewCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/billRunPreview'
example:
id: 8ad0934e8727f642018729728eae1b2a
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28 11:19:57'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28 11:19:46'
assume_renewal: auto_renew_only
batches:
- Batch3
- Batch4
charges_excluded:
- one_time
- usage
include_draft_items: false
include_evergreen_subscriptions: true
target_date: '2023-01-01'
state_transitions:
complete_time: '2023-03-28 11:19:57'
processing_start_time: '2023-03-28 11:19:47'
file:
url: 8ad0962d8727efba01872972b9f235a5
billing_preview_run_number: BPR-00000039
state: completed
number_of_accounts_succeeded: 1
number_of_accounts: 1
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/query_runs/{query_run_id}:
get:
operationId: getQueryRun
summary: Retrieve a query run
tags:
- Query Runs
description: Retrieves the query run with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: query_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: query_run_id
required: true
schema:
type: string
description: query_run_id
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/query_runs/8ce80b3b-f2c8-45e2-b495-03703754dbff
--header 'Authorization: Bearer
cbf5f7c69105431289eee98fa13c8b83' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
QueryRun queryRunResponse =
zuoraClient.queryRuns().getQueryRun("8ce80b3b-f2c8-45e2-b495-03703754dbff",null);
System.out.println(queryRunResponse);
- lang: JavaScript
label: Node
source: >-
const queryRunResponse = await
zuoraClient.queryRuns.getQueryRun("8ce80b3b-f2c8-45e2-b495-03703754dbff");
console.log(queryRunResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/queryRun'
example:
created_by_id: 47b43d42-f237-4bfa-82b5-5602e2282e3d
id: 8ce80b3b-f2c8-45e2-b495-03703754dbff
sql: SELECT * FROM subscription
remaining_attempts: 3
updated_time: '2023-04-12T00:26:42.227Z'
file:
id: 8ce80b3b-f2c8-45e2-b495-03703754dbff_1833251171549653.dsv
url: >-
https://owl-auw2-sbx01-query-result.s3.us-west-2.amazonaws.com/8ce80b3b-f2c8-45e2-b495-03703754dbff_1833251171549653.dsv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLXdlc3QtMiJIMEYCIQDa0aBFH4e%2FOtmrY8sNsiXxnPLClpwjzipqMFdoQ1Pa8QIhAKo4NtaMa8rxoHHh5O31b%2BvuWlxkgaibQfLl1nF8sKnaKvwDCLD%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQBBoMMDQ5NzUxNzE2Nzc0Igx%2FKDjiqJmh1eRP%2FOYq0APDiPAxPWUIAZXyCa76ja6HSqH9QWVPnH%2BVcUEdww8f45l1x8naqU%2FagnKkZct8Bts30Axmeo4iinKLVnFfIfCvjJn1dXg%2FL2gRE2lg7%2BAe3HTFwcRhQivCAKqBhKrQb%2F19Ut%2BgF7vaeS9TtBq3YuItoNUnZkIcJq2UIZYSpvtf4HYuJk6txis5DFH9yzLaPPpcrJ71qF6A%2BHWyAuV%2BVwWgjLXAk1aD9teFf%2F13VvqhdU1ILkTxD8P57cEAa0Iui%2BJJIO9e5O0lk%2BzeZ1eQ3Lbe6PGOeRQcGW6Qkc8cIsXhQb04GPixqaYH1luZQ0QB0AMVH1NCh47w4uhCul8ECgFn33iwY97VHjFl%2FU4lJbTtpnR5YHkuCFps4COSs7VP%2B8y1SSpu1mfsl4OXIH9OT5Abs45sf2CkWsaCmRmfigL25XTWy7x3rsFic9lYnOVKnEj3mN99GzgM2Ms2GsV1lxV9gk8M3V1I6OBCl8o6PVQTDEsr4ZJ3Rs%2FyJg7q0pEPWXLDao4VwA3lQzvQCmvjMHJDXcFgiGkWQm%2B0WzU2cs1BM7JLs5RKUpRGLWBz%2FFvzdA1%2F0rxbE3rdBQklJwKGM6PWE0PUoh7AySU8BZLutYLOUTCrytehBjqkAd9UvURTKb8SFyWeSDwJ1uTEbW3KOBHgbmzbVyihyFJMphgHd3LBwAZoIW%2BR8o4C0BhJgdpaitRHf7GJt2cslLcrxFNNCXcdbX5PlVuphk1hybjrExpmuzjxtbQSbjHS53XwNgRnMPV3zb4macrAECWTqC5il5JlqCYRtaKxSufUZbqZecI%2BO1doJIYrUi7ItCex8WuLCy%2B7Bsm904c2CwJSMTBW&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230412T002642Z&X-Amz-SignedHeaders=host&X-Amz-Expires=14400&X-Amz-Credential=ASIAQXFLO6OTGM4JW52F%2F20230412%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=1137ea00b89ec0f53423f7fba44ffbbe7e1051ac9dcfd0d169d3a42b6900ecd5
content_type: dsv
number_of_rows: 4639
state: complete
column_separator: ':'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/query_runs:
post:
operationId: createQueryRun
summary: Create a query run
tags:
- Query Runs
description: Creates a new query run job.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/queryRunCreateRequest'
example:
sql: SELECT * FROM subscription
content_type: dsv
read_deleted: false
column_separator: ':'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: query_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url https://rest.apisandbox.zuora.com/v2/query_runs --header 'Authorization: Bearer 2875a82617584dd8b521d1a9dbda1452' --header 'Content-Type: application/json' --data '{ "sql": "SELECT a.name AS account_name, sub.name AS sub_name, sub.version AS sub_version, sub.termstartdate, sub.termenddate, sub.source__c FROM subscription sub INNER JOIN account a ON sub.accountid = a.id where sub.status in ('\''Active'\'','\''Cancelled'\'') and source__c like '\''Mark%'\'' order by a.name, sub.name, sub.version",
"content_type": "json"
}'
- lang: Java
label: Java
source: >-
QueryRunCreateRequest queryRunCreateRequest = new
QueryRunCreateRequest()
.sql("SELECT * FROM subscription")
.contentType(QueryRunCreateRequest.queryRunPostFileContentTypeEnum.DSV)
.readDeleted(false)
.columnSeparator(:);
QueryRun newQueryRun =
zuoraClient.queryRuns().createQueryRun(queryRunCreateRequest);
- lang: JavaScript
label: Node
source: >-
const queryRunCreateRequest = {
sql: "SELECT * FROM subscription",
content_type: "dsv",
read_deleted: false,
column_separator: ":"
};
const newQueryRun = await
zuoraClient.queryRuns.createQueryRun(queryRunCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/queryRun'
example:
created_by_id: 47b43d42-f237-4bfa-82b5-5602e2282e3d
id: 8ce80b3b-f2c8-45e2-b495-03703754dbff
sql: SELECT * FROM subscription
remaining_attempts: 3
updated_time: '2023-04-12T00:26:42.227Z'
file:
id: 8ce80b3b-f2c8-45e2-b495-03703754dbff_1833251171549653.dsv
url: >-
https://owl-auw2-sbx01-query-result.s3.us-west-2.amazonaws.com/8ce80b3b-f2c8-45e2-b495-03703754dbff_1833251171549653.dsv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLXdlc3QtMiJIMEYCIQDa0aBFH4e%2FOtmrY8sNsiXxnPLClpwjzipqMFdoQ1Pa8QIhAKo4NtaMa8rxoHHh5O31b%2BvuWlxkgaibQfLl1nF8sKnaKvwDCLD%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQBBoMMDQ5NzUxNzE2Nzc0Igx%2FKDjiqJmh1eRP%2FOYq0APDiPAxPWUIAZXyCa76ja6HSqH9QWVPnH%2BVcUEdww8f45l1x8naqU%2FagnKkZct8Bts30Axmeo4iinKLVnFfIfCvjJn1dXg%2FL2gRE2lg7%2BAe3HTFwcRhQivCAKqBhKrQb%2F19Ut%2BgF7vaeS9TtBq3YuItoNUnZkIcJq2UIZYSpvtf4HYuJk6txis5DFH9yzLaPPpcrJ71qF6A%2BHWyAuV%2BVwWgjLXAk1aD9teFf%2F13VvqhdU1ILkTxD8P57cEAa0Iui%2BJJIO9e5O0lk%2BzeZ1eQ3Lbe6PGOeRQcGW6Qkc8cIsXhQb04GPixqaYH1luZQ0QB0AMVH1NCh47w4uhCul8ECgFn33iwY97VHjFl%2FU4lJbTtpnR5YHkuCFps4COSs7VP%2B8y1SSpu1mfsl4OXIH9OT5Abs45sf2CkWsaCmRmfigL25XTWy7x3rsFic9lYnOVKnEj3mN99GzgM2Ms2GsV1lxV9gk8M3V1I6OBCl8o6PVQTDEsr4ZJ3Rs%2FyJg7q0pEPWXLDao4VwA3lQzvQCmvjMHJDXcFgiGkWQm%2B0WzU2cs1BM7JLs5RKUpRGLWBz%2FFvzdA1%2F0rxbE3rdBQklJwKGM6PWE0PUoh7AySU8BZLutYLOUTCrytehBjqkAd9UvURTKb8SFyWeSDwJ1uTEbW3KOBHgbmzbVyihyFJMphgHd3LBwAZoIW%2BR8o4C0BhJgdpaitRHf7GJt2cslLcrxFNNCXcdbX5PlVuphk1hybjrExpmuzjxtbQSbjHS53XwNgRnMPV3zb4macrAECWTqC5il5JlqCYRtaKxSufUZbqZecI%2BO1doJIYrUi7ItCex8WuLCy%2B7Bsm904c2CwJSMTBW&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230412T002642Z&X-Amz-SignedHeaders=host&X-Amz-Expires=14400&X-Amz-Credential=ASIAQXFLO6OTGM4JW52F%2F20230412%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=1137ea00b89ec0f53423f7fba44ffbbe7e1051ac9dcfd0d169d3a42b6900ecd5
content_type: dsv
number_of_rows: 4639
state: complete
column_separator: ':'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/query_runs/{query_run_id}/cancel:
post:
operationId: cancelQueryRun
summary: Cancel a query run
tags:
- Query Runs
description: >-
Cancels a query run. This operation is only applicable if the state of
the query run is `accepted` or `in_progress`.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: query_run.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`created_by_id`, `id`, `sql`, `remaining_attempts`, `updated_time`, `file`, `number_of_rows`, `processing_duration`, `state`, `column_separator`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: query_run_id
required: true
schema:
type: string
description: query_run_id
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/query_runs/cfefa1e7-61d9-4cd5-8f60-d995518e3546/cancel
--header 'Authorization: Bearer
cbf5f7c69105431289eee98fa13c8b83' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
QueryRun canceledQueryRun =
zuoraClient.queryRuns().cancelQueryRun("8ce80b3b-f2c8-45e2-b495-03703754dbff");
System.out.println(canceledQueryRun);
- lang: JavaScript
label: Node
source: >-
const canceledQueryRun = await
zuoraClient.queryRuns.cancelQueryRun("8ce80b3b-f2c8-45e2-b495-03703754dbff");
console.log(canceledQueryRun);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/queryRun'
example:
created_by_id: 47b43d42-f237-4bfa-82b5-5602e2282e3d
id: 94d968ba-e5d1-437a-a86f-bb7c486e8987
sql: SELECT * FROM subscription
remaining_attempts: 3
updated_time: '2023-04-12T17:42:28.911Z'
state: cancelled
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments:
get:
operationId: getFulfillments
summary: List fulfilllments
tags:
- Fulfillments
description: >-
Returns a dictionary with a data property that contains an array of
fulfillments, starting after the cursor, if used. Each entry in the
array is a separate fulfillment object. If no more fulfillment are
available, the resulting array will be empty. This request should never
return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/fulfillments' --header
'Authorization: Bearer 08dacd3fe8b648f6861d5eb506d02a86'
--header 'Content-Type: application/json'
- lang: Java
label: Java
source: >-
ListFulfillmentResponse fulfillmentListResponse =
zuoraClient.fulfillment().getFulfillments(null,null,null,null);
System.out.println(fulfillmentListResponse);
- lang: JavaScript
label: Node
source: >-
const fulfillmentResponse = await
zuoraClient.fulfillments.getFulfillments({
filter: [
"id.EQ:08dacd3fe8b648f6861d5eb506d02a86"
]})
console.log(fulfillmentResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/filfillmentListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createFulfillment
summary: Create a fulfillment
tags:
- Fulfillments
description: Creates a new fulfillment object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentCreateRequest'
example:
order_line_item_id: 8ad085e287142db601872469b9ec0944
description: Create a fulfillment
fulfillment_date: '2022-03-01'
type: delivery
quantity: 2
state: booked
external_id: '1201'
tracking_number: '0987'
fulfillment_system: Provision
items:
- description: Create Item
fulfillment_number: F-00000021
fulfillment_item_number: Item 01
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/fulfillments --header
'Authorization: Bearer d71a4363b94f42bca6e1453892818775'
--header 'Content-Type: application/json' --data '{
"order_line_item_id": "8ad085e287142db601872469b9ec0944",
"description": "create fulfillment",
"fulfillment_date": "2022-03-25",
"type": "delivery",
"quantity": 2,
"state": "processing",
"external_id": "1234",
"tracking_number": "0987",
"fulfillment_system": "Test System",
"processing_options": {
"document_date": "2022-03-25",
"target_date": "2022-03-25",
"collection_method": "create_invoice"
}
}'
- lang: Java
label: Java
source: >-
FulfillmentCreateRequest fulfillmentCreateRequest = new
FulfillmentCreateRequest()
.order_line_item_id("8ad085e287142db601872469b9ec0944")
.fulfillment_date("2022-03-25")
.type("delivery");
Fulfillment fulfillment =
zuoraClient.fulfillments().createFulfillment(fulfillmentCreateRequest);
- lang: JavaScript
label: Node
source: >-
const fulfillmentCreateRequest = {
order_line_item_id: '8ad085e287142db601872469b9ec0944',
fulfillment_date: '2022-03-25',
type: 'delivery'
};
const newFulfillment = await
zuoraClient.fulfillments.createFulfillment(contactFulfillmentRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillment'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments/{fulfillment_id}:
get:
operationId: getFulfillment
summary: Retrieve a fulfillment
tags:
- Fulfillments
description: Retrieves the fulfillment with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: fulfillment_id
required: true
schema:
type: string
description: ID of the fulfillment.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/fulfillments/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
Fulfillment fulfillmentResponse =
zuoraClient.fulfillment().getFulfillment(fulfillment.getId());
System.out.println(fulfillmentResponse);
- lang: JavaScript
label: Node
source: >-
const fulfillmentResponse = await
zuoraClient.fulfillments.getFulfillment('8ad09bce844283060184475e7ee669f0');
console.log(fulfillmentResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillment'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields:
field__c: custom field value
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-0000002001234
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
target_date: '2022-03-31'
description: Create a fulfillment
tracking_number: '09827'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateFulfillment
summary: Update a fulfillment
tags:
- Fulfillments
description: >-
Updates the specified fulfillment by setting the values of the
parameters passed. Any parameters not provided will be left unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentPatchRequest'
example:
quantity: 5
state: booked
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
tracking_number: '09828'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: fulfillment_id
required: true
schema:
type: string
description: ID of the fulfillment.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/fulfillments/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"quantity": 5,
"state": "booked",
"external_id": "0987",
"tracking_number": "09827"
}'
- lang: Java
label: Java
source: >-
Fulfillment oldFulfillment =
zuoraClient.fulfillments().getFulfillment("8ad0991582aa848e0182ae9dad214dd0");
FulfillmentPatchRequest fulfillmentPatchRequest = new
FulfillmentPatchRequest()
.tracking_number("09827")
.external_id("0987")
.state("booked"));
Fulfillment updatedFulfillment =
zuoraClient.fulfillments().updateFulfillment(oldFulfillment.getId(),fulfillmentPatchRequest);
- lang: JavaScript
label: Node
source: "\nconst fulfillmentId = newFulfillment.id;\n\nconst fulfillmentPatchRequest = {\n\tquantity: 5,\n\tstate: \"booked\",\n\texternal_id: \"0987\",\n\ttracking_number: \"09827\"\n};\n \nconst updatedFulfillment = await zuoraClient.fulfillments.updateFulfillment(fulfillmentId, fulfillmentPatchRequest);\n "
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillment'
example:
id: 8ad08d298727e378018728f2a2452b0e
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-28T09:00:42-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T09:00:02-07:00'
custom_fields: {}
order_line_item_id: 8ad085e287142db601872469b9ec0944
fulfillment_number: F-00000020
fulfillment_date: '2022-03-01'
quantity: 5
state: booked
description: Create a fulfillment
tracking_number: '09828'
fulfillment_system: Provision
external_id: b12487f0-cd81-11ed-82b6-c9f5c53749cc
revenue:
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
location: Oregon
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteFulfillment
summary: Delete a fulfillment
tags:
- Fulfillments
description: Permanently deletes a fulfillment. It cannot be undone.
parameters:
- in: path
name: fulfillment_id
required: true
schema:
type: string
description: ID of the fulfillment.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/fulfillments/8ad08c0f7d0972ea017d0a705e8059ba'
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.fulfillments().deleteFulfillment(createdFulfillment.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const fulfillmentDeleteResponse = await
zuoraClient.fulfillments.deleteFulfillment('8ad09bce844283060184475e7ee669f0');
console.log(fulfillmentDeleteResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments_items/{fulfillment_item_id}:
get:
operationId: getFulfillmentItem
summary: Retrieve a fulfillment item
tags:
- Fulfillment Items
description: Retrieves the fulfillment item with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: fulfillment_item_id
required: true
schema:
type: string
description: ID of the fulfillment item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/fulfillments_items/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
FulfillmentItem fulfillmentItemResponse =
zuoraClient.fulfillmentItem().getFulfillmentItem(fulfillmentItem.getId());
System.out.println(fulfillmentItemResponse);
- lang: JavaScript
label: Node
source: >-
const fulfillmentItemResponse = await
zuoraClient.fulfillmentItems.getFulfillmentItem('8ad09bce844283060184475e7ee669f0');
console.log(fulfillmentItemResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItem'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updateFulfillmentItem
summary: Update a fulfillment item
tags:
- Fulfillment Items
description: >-
Updates the specified fulfillment item by setting the values of the
fields passed. Any fields not provided remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItemPatchRequest'
example:
description: Update Item Number
fulfillment_item_number: Item 003
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: fulfillment_item_id
required: true
schema:
type: string
description: ID of the fulfillment item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/fulfillments_items/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"description":"Update Item Number",
"fulfillment_item_number": "Item 3.1"
}'
- lang: Java
label: Java
source: >-
FulfillmentItem oldFulfillmentItem =
zuoraClient.fulfillmentItems().getFulfillmentItem("8ad0991582aa848e0182ae9dad214dd0");
FulfillmentItemPatchRequest fulfilmentItemPatchRequest = new
FulfillmentItemPatchRequest()
.description(Update Item Number)
.fulfillment_item_number("USA");
FulfillmentItem updatedFulfilmentItem =
zuoraClient.fulfillmentItems().updateFulfillmentItem(oldFulfillmentItem.getId(),fulfillmentItemPatchRequest);
- lang: JavaScript
label: Node
source: >-
const fulfillmentItemId = newFulfillmentItem.id;
const fulfillmentItemPatchRequest = {
description: 'Update Item Number',
fulfillment_item_number: 'Item 3.1'
};
const updatedFulfillmentItem = await
zuoraClient.fulfillmentItems.updateFulfillmentItems(fulfillmentItemId,
PatchRequest);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItem'
example:
id: 8ad09e208727f63f01872967daf72c59
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Update Item Number
fulfillment_item_number: Item 003
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
delete:
operationId: deleteFulfillmentItem
summary: Delete a fulfillment item
tags:
- Fulfillment Items
description: Permanently deletes a fulfillment item. This operation cannot be undone.
parameters:
- in: path
name: fulfillment_item_id
required: true
schema:
type: string
description: ID of the fulfillment item.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: delete
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request DELETE --url
'https://rest.apisandbox.zuora.com/v2/fulfillments_items/8ad08c0f7d0972ea017d0a705e8059ba'
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
SuccessResponse result =
zuoraClient.fulfillmentItems().deleteFulfillmentItem(createdFulfillmentItem.getId());
System.out.println(result);
- lang: JavaScript
label: Node
source: >-
const fulfillmentItemsDeleteResponse = await
zuoraClient.fulfillmentItems.deleteFulfillmentItems('8ad09bce844283060184475e7ee669f0');
console.log(fulfillmentItemsDeleteResponse);
x-group-parameters: true
responses:
'204':
description: Default Response
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments_items:
get:
operationId: getFulfillmentItems
summary: List fulfillment items
tags:
- Fulfillment Items
description: >-
Returns a dictionary with a data property that contains an array of
fulfillment items, starting after the cursor, if used. Each entry in the
array is a separate fulfillment item object. If no more fulfillment item
are available, the resulting array will be empty. This request should
never return an error.
parameters:
- in: query
name: cursor
required: false
schema:
type: string
x-java-sdk-legacy-param: true
description: >-
A cursor for use in pagination. A cursor defines the starting place
in a list. For instance, if you make a list request and receive 100
objects, ending with `next_page=W3sib3JkZXJ=`, your subsequent call
can include `cursor=W3sib3JkZXJ=` in order to fetch the next page of
the list.
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: sort[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive query parameter that specifies the sort order of
the list, which can be either ascending (e.g. `account_number.asc`)
or descending (e.g. `account_number.desc`). You cannot sort on
properties that are arrays. If the array-type properties are
specified for the `sort[]` parameter, they are ignored.
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
default: 30
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: list
x-is-list-operation: true
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
'https://rest.apisandbox.zuora.com/v2/fulfillments_items'
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
ListFulfillmentItemResponse fulfillmentItemListResponse =
zuoraClient.fulfillmentItems().getFulfillmentItems(null,null,null,null);
System.out.println(fulfillmentItemsListResponse);
- lang: JavaScript
label: Node
source: >-
const fulfillmentItemResponse = await
zuoraClient.fulfillmentItems.getFulfillmentItems({
filter: [
"id.EQ:08dacd3fe8b648f6861d5eb506d02a86"
]})
console.log(fulfillmentItemResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/filfillmentItemListResponse'
example:
next_page: >-
W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=
data:
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
- id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
post:
operationId: createFulfillmentItem
summary: Create a fulfillment item
tags:
- Fulfillment Items
description: Creates a new fulfillment item object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItemCreateRequest'
example:
description: Create a fulfillment Item
fulfillment_number: F-00000020
fulfillment_item_number: Item 3
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/fulfillments_items
--header 'Authorization: Bearer
d71a4363b94f42bca6e1453892818775' --header 'Content-Type:
application/json' --data '{
"description": "Create fulfillment item",
"fulfillment_number": "F-00000020",
"fulfillment_item_number": "Item 3"
}'
- lang: Java
label: Java
source: >-
FulfillmentItemCreateRequest fulfillmentItemCreateRequest = new
FulfillmentItemCreateRequest()
.description("Create fulfillment item")
.fulfillment_number("F-00000020")
.fulfillment_item_number("Item 3");
FulfillmentItem fulfillmentItem =
zuoraClient.fulfillmentItems().createFulfillmentItem(fulfillmentItemCreateRequest);
- lang: JavaScript
label: Node
source: >-
const fulfillmentItemCreateRequest = {
description: 'Create fulfillment item',
fulfillment_number: 'F-00000020',
fulfillment_item_number: 'Item 3'
};
const newFulfillmentItem = await
zuoraClient.fulfillmentItems.createFulfillmentItem(fulfillmentItemCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItem'
example:
id: 8ad08ccf8437067601843a7af4e64rq3
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-03-29T10:04:53-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-03-28T11:08:04-07:00'
custom_fields:
field__c: custom field value
description: Create a fullfillment item
fulfillment_item_number: Item 3
fulfillment_id: 8ad08d298727e378018728f2a2452b0e
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments/bulk_create:
post:
operationId: createFulfillments
summary: Create fulfillments
tags:
- Fulfillments
description: Creates multiple fulfillments.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentCreateBulkRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `state`, `description`, `quantity`, `order_line_item_id`, `fulfillment_number`, `revenue`, `fulfillment_date`, `tracking_number`, `carrier`, `fulfillment_system`, `location`, `external_id`, `type`, `target_date`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: credit_memo_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `credit_memo_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `service_end`, `service_start`, `accounts_receivable_account`, `on_account_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `subtotal`, `invoice_item_id`, `document_item_date`
</details>
- in: query
name: invoice_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: bulkCreate
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentCreateBulkResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/fulfillments_items/bulk_create:
post:
operationId: createFulfillmentItems
summary: Create fulfillment items
tags:
- Fulfillment Items
description: Bulk create fulfillment items.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItemCreateBulkRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: fulfillment_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `fulfillment_id`, `description`, `fulfillment_item_number`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: bulkCreate
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/fulfillmentItemCreateBulkResponse'
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedule_items/{payment_schedule_item_id}:
get:
operationId: getPaymentScheduleItem
summary: Retrieve a payment schedule item
tags:
- Payment Schedule Items
description: Retrieves the payment schedule item with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_item_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule item. Can be either
`payment_schedule_item_id` or `payment_schedule_item_number`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/payment_schedules_items/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
PaymentScheduleItem paymentScheduleItemsResponse =
zuoraClient.paymentScheduleItems().getPaymentScheduleItem(paymentScheduleItems.getId());
System.out.println(paymentScheduleItemsResponse);
- lang: JavaScript
label: Node
source: >-
const paymentScheduleItemsResponse = await
zuoraClient.paymentScheduleItems.getPaymentScheduleItem('8ad09bce844283060184475e7ee669f0');
console.log(paymentScheduleItemsResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePaymentScheduleItem
summary: Update a payment schedule item
tags:
- Payment Schedule Items
description: >-
Updates the specified payment schedule item by setting the values of the
parameters passed. Any parameters not provided will remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItemPatch'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_item_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule item. Can be either
`payment_schedule_item_id` or `payment_schedule_item_number`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/payment_schedule_items/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"unlink": [{
"id": "8ad0922589de70ef0189df1b78c50ff7"
}]
}'
- lang: Java
label: Java
source: >-
PaymentScheduleItem oldPaymentScheduleItem =
zuoraClient.paymentScheduleItems().getPaymentScheduleItem("8ad0991582aa848e0182ae9dad214dd0");
PaymentScheduleItemPatchRequest paymentScheduleItemPatchRequest =
new PaymentScheduleItemPatchRequest()
.unlink("8ad0922589de70ef0189df1b78c50ff7"));
PaymentScheduleItem updatedPaymentScheduleItem =
zuoraClient.paymentScheduleItems().updatePaymentScheduleItem(oldPaymentScheduleItem.getId(),paymentScheduleItemPatchRequest);
- lang: JavaScript
label: Node
source: "\nconst paymentScheduleItemId = newPaymentScheduleItem.id;\n\nconst paymentScheduleItemPatchRequest = {\n\tunlink: [{\n\t\tid: \"8ad0922589de70ef0189df1b78c50ff7\"\n\t}]\n};\n \nconst updatedPaymentScheduleItem = await zuoraClient.paymentScheduleItems().updatePaymentScheduleItem(paymentScheduleItemId, paymentSchedulesPatchRequest);\n "
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedule_items:
post:
operationId: createPaymentScheduleItem
summary: Create a payment schedule item
tags:
- Payment Schedule Items
description: Creates a new Payment Schedule Item object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItemCreateRequest'
example:
payment_schedule_id: 8ad0940889b71fc20189b7e8eec6416e
amount: 6
run_hour: 1
scheduled_date: '2023-08-02'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_schedule_items
--header 'Authorization: Bearer
d71a4363b94f42bca6e1453892818775' --header 'Content-Type:
application/json' --data '{
"payment_schedule_id": "8ad085e289e27bc80189e44803796d07",
"amount": 6,
"run_hour": 1,
"scheduled_date": "2023-09-29"
}'
- lang: Java
label: Java
source: >-
PaymentScheduleItemCreateRequest paymentScheduleItemCreateRequest =
new PaymentScheduleItemCreateRequest()
.payment_schedule_id("8ad085e287142db601872469b9ec0944")
.scheduled_date("2023-07-26")
.amount(100)
.run_hour(1);
PaymentScheduleItem paymentScheduleItem =
zuoraClient.paymentScheduleItems().createPaymentScheduleItem(paymentScheduleItemCreateRequest);
- lang: JavaScript
label: Node
source: >-
const paymentScheduleItemCreateRequest = {
payment_schedule_id: '8ad085e287142db601872469b9ec0944',
scheduled_date: '2023-07-26',
amount: 100,
run_hour: 1
};
const newPaymentScheduleItem = await
zuoraClient.paymentScheduleItems.createPaymentScheduleItem(paymentScheduleItemCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedule_items/{payment_schedule_item_id}/cancel:
post:
operationId: cancelPaymentScheduleItem
summary: Cancel a payment schedule item
tags:
- Payment Schedule Items
description: Cancels the payment schedule item with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_item_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule item. Can be either
`payment_schedule_item_id` or `payment_schedule_item_number`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_schedule_items/8ad085e289e27bc80189e44803cb6d4e/cancel
--header 'Content-Type: application/json' --header 'Authorization:
Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{}'
- lang: Java
label: Java
source: |2-
PaymentScheduleItem paymentScheduleItem = zuoraClient.paymentScheduleItems().cancelPaymentScheduleItem("8ad085e289e27bc80189e44803cb6d4e", null);
- lang: JavaScript
label: Node
source: >2-
const cancelPaymentScheduleItem = await
zuoraClient.paymentScheduleItems.cancelPaymentScheduleItem("8ad085e289e27bc80189e44803cb6d4e");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedule_items/{payment_schedule_item_id}/retry:
post:
operationId: retryPaymentScheduleItem
summary: Retry a payment shedule item
tags:
- Payment Schedule Items
description: Retries the payment schedule item with the given ID.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItemRetry'
example:
payment_gateway_id: 2c92c0f86a8dd422016a941ee0d82c7f
payment_method_id: 8ad081c689de67b50189de7b15b7142a
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_item_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule item. Can be either
`payment_schedule_item_id` or `payment_schedule_item_number`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl --request POST
--url https://rest.apisandbox.zuora.com/v2/payment_schedule_items/8ad085e289e27bc80189e44803cb6d4e/retry
--header 'Content-Type: application/json' --header 'Authorization: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{
"payment_gateway_id": "2c92c0f86a8dd422016a941ee0d82c7f",
"payment_method_id": "8ad081c689de67b50189de7b15b7142a"
}'
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedule_items/{payment_schedule_item_id}/skip:
post:
operationId: skipPaymentScheduleItem
summary: Skip a payment schedule item
tags:
- Payment Schedule Items
description: Skips the payment schedule item with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_item_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule item. Can be either
`payment_schedule_item_id` or `payment_schedule_item_number`
- in: header
name: zuora-track-id
required: false
description: >-
A custom identifier for tracking API requests. If you set a value
for this header, Zuora returns the same value in the response
header. This header enables you to track your API calls to assist
with troubleshooting in the event of an issue. The value of this
field must use the US-ASCII character set and must not include any
of the following characters: colon (:), semicolon (;), double quote
("), or quote (').
schema:
type: string
- in: header
name: async
required: false
description: >-
Making asynchronous requests allows you to scale your applications
more efficiently by leveraging Zuora's infrastructure to enqueue and
execute requests for you without blocking. These requests also use
built-in retry semantics, which makes them much less likely to fail
for non-deterministic reasons, even in extreme high-throughput
scenarios. Meanwhile, when you send a request to one of these
endpoints, you can expect to receive a response in less than 150
milliseconds and these calls are unlikely to trigger rate limit
errors. If set to true, Zuora returns a 202 Accepted response, and
the response body contains only a request ID.
schema:
type: boolean
- in: header
name: zuora-entity-ids
required: false
description: >-
An entity ID. If you have multi-entity enabled and the authorization
token is valid for more than one entity, you must use this header to
specify which entity to perform the operation on. If the
authorization token is only valid for a single entity, or you do not
have multi-entity enabled, you do not need to set this header.
schema:
type: string
- in: header
name: idempotency-key
required: false
description: >-
Specify a unique idempotency key if you want to perform an
idempotent POST or PATCH request. Do not use this header in other
request types. This idempotency key should be a unique value, and
the Zuora server identifies subsequent retries of the same request
using this value. For more information, see [Idempotent
Requests](https://developer.zuora.com/docs/guides/idempotent-requests/).
schema:
type: string
- in: header
name: accept-encoding
required: false
description: >-
Include a `accept-encoding: gzip` header to compress responses,
which can reduce the bandwidth required for a response. If
specified, Zuora automatically compresses responses that contain
over 1000 bytes. For more information about this header, see
[Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
- in: header
name: content-encoding
required: false
description: >-
Include a `content-encoding: gzip` header to compress a request.
Upload a gzipped file for the payload if you specify this header.
For more information, see [Request and Response
Compression](https://developer.zuora.com/docs/guides/request-and-response-compression/).
schema:
type: string
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: |-
curl --request POST
--url https://rest.apisandbox.zuora.com/v2/payment_schedule_items/8ad085e289e27bc80189e44803cb6d4e/skip
--header 'Content-Type: application/json' --header 'Authorization: Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{}'
- lang: Java
label: Java
source: >2-
PaymentScheduleItem paymentScheduleItem =
zuoraClient.paymentScheduleItems().skipPaymentScheduleItem("8ad085e289e27bc80189e44803cb6d4e");
- lang: JavaScript
label: Node
source: >2-
const skipPaymentScheduleItem = await
zuoraClient.paymentScheduleItems.skipPaymentScheduleItem("8ad085e289e27bc80189e44803cb6d4e");
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleItem'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: Payments schedule item one created
number_of_payments: 1
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedules/{payment_schedule_id}:
get:
operationId: getPaymentSchedule
summary: Retrieve a payment schedule
tags:
- Payment Schedules
description: Retrieves the payment schedule with the given ID.
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule. Can be either
`payment_schedule_number` or `payment_schedule_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: get
x-code-samples:
- lang: Curl
label: cURL
source: >
curl --request GET --url
https://rest.apisandbox.zuora.com/v2/payment_schedules/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
08dacd3fe8b648f6861d5eb506d02a86' --header 'Content-Type:
application/json'
- lang: Java
label: Java
source: >-
PaymentSchedule paymentSchedulesResponse =
zuoraClient.paymentSchedules().getPaymentSchedule(paymentSchedules.getId());
System.out.println(paymentSchedulesResponse);
- lang: JavaScript
label: Node
source: >-
const paymentSchedulesResponse = await
zuoraClient.paymentSchedules.getPaymentSchedule('8ad09bce844283060184475e7ee669f0');
console.log(paymentSchedulesResponse);
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentSchedule'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: ''
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
patch:
operationId: updatePaymentSchedule
summary: Update a payment schedule
tags:
- Payment Schedules
description: >-
Updates the specified payment schedule by setting the values of the
parameters passed. Any parameters not provided will remain unchanged.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentSchedulePatchRequest'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule. Can be either
`payment_schedule_number` or `payment_schedule_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: update
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request PATCH --url
https://rest.apisandbox.zuora.com/v2/payment_schedule/8ad08c0f7d0972ea017d0a705e8059ba
--header 'Authorization: Bearer
8e8a7aec6fa4476d97a52b52dc3cc52f' --header 'Content-Type:
application/json' --data '{
"description": "update payment schedule"
}'
- lang: Java
label: Java
source: >-
PaymentSchedule oldPaymentSchedule =
zuoraClient.paymentSchedules().getPaymentSchedule("8ad0991582aa848e0182ae9dad214dd0");
PaymentSchedulePatchRequest paymentSchedulePatchRequest = new
PaymentSchedulePatchRequest()
.description("update payment schedule"));
PaymentSchedule updatedPaymentSchedule =
zuoraClient.paymentSchedules().updatePaymentSchedule(oldPaymentSchedule.getId(),paymentSchedulePatchRequest);
- lang: JavaScript
label: Node
source: "\nconst paymentScheduleId = newPaymentSchedule.id;\n\nconst paymentSchedulePatchRequest = {\n\tdescription: \"update payment schedule\"\n};\n \nconst updatedPaymentSchedule = await zuoraClient.paymentSchedules().updatePaymentSchedule(paymentSchedulesId, paymentSchedulesPatchRequest);\n "
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentSchedule'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: ''
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedules:
post:
operationId: createPaymentSchedule
summary: Create a payment schedule
tags:
- Payment Schedules
description: Creates a new Payment Schedule object.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleCreateRequest'
example:
account_id: 8ad09e20896d5f7f018970bbca5d3508
amount: 100
currency: USD
start_date: '2023-07-26'
payment_method_id: 8ad09e20896d5f7f018970bbca193501
number_of_payments: 1
billing_document:
billing_document_number: INV00009585
type: invoice
items:
- amount: 100
run_hour: 1
scheduled_date: '2023-07-26'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: create
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_schedule --header
'Authorization: Bearer d71a4363b94f42bca6e1453892818775'
--header 'Content-Type: application/json' --data '{
"account_id": "8ad09e20896d5f7f018970bbca5d3508",
"amount": 100,
"currency": "USD",
"start_date": "2023-07-26",
"payment_method_id": "8ad09e20896d5f7f018970bbca193501",
"number_of_payments": 1,
"billing_document": {
"billing_document_number": "INV00009585",
"type": "invoice"
}
}'
- lang: Java
label: Java
source: >-
PaymentScheduleCreateRequest paymentScheduleCreateRequest = new
PaymentScheduleCreateRequest()
.account_id("8ad085e287142db601872469b9ec0944")
.start_date("2023-07-26")
.amount(100)
.number_of_payments(1);
PaymentSchedule paymentSchedule =
zuoraClient.paymentSchedules().createPaymentSchedule(paymentScheduleCreateRequest);
- lang: JavaScript
label: Node
source: >-
const paymentScheduleCreateRequest = {
account_id: '8ad085e287142db601872469b9ec0944',
start_date: '2023-07-26',
amount: 100,
number_of_payments: 1
};
const newPaymentSchedule = await
zuoraClient.paymentSchedules.createPaymentSchedule(paymentScheduleCreateRequest);
x-group-parameters: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentSchedule'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: ''
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
/payment_schedules/{payment_schedule_id}/cancel:
post:
operationId: cancelPaymentSchedule
summary: Cancel a payment schedule
tags:
- Payment Schedules
description: Cancels the payment schedule with the given ID.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentScheduleCancel'
required: true
parameters:
- in: query
name: fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule.fields[]
required: false
schema:
type: array
deprecated: true
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `description`, `next_payment_date`, `payment_schedule_number`, `number_of_payments`, `prepayment`, `start_date`, `run_hour`, `state`, `recent_payment_date`, `total_payments_errored`, `total_payments_processed`, `total_amount`, `debit_memo_id`, `invoice_id`
</details>
- in: query
name: payment_schedule_item.fields[]
required: false
schema:
type: array
deprecated: false
x-java-sdk-legacy-param: false
x-java-sdk-fields-param: true
items:
type: string
example:
- id,created_time
description: |-
Allows you to specify which fields are returned in the response.
<details>
<summary> Accepted values </summary>
`custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `amount`, `balance`, `currency`, `debit_memo_id`, `invoice_id`, `payment_id`, `payment_method_id`, `description`, `prepayment`, `payment_gateway_id`, `run_hour`, `state`, `scheduled_date`, `payment_schedule_item_number`, `payment_schedule_id`, `cancellation_reason`, `error_message`, `payment_option_id`
</details>
- in: query
name: expand[]
required: false
schema:
type: array
x-java-sdk-legacy-param: true
items:
type: string
description: >-
Allows you to expand responses by including related object
information in a single call. See the [Expand
responses](https://developer.zuora.com/quickstart-api/tutorial/expand-responses/)
section of the Quickstart API Tutorials for detailed instructions.
- in: query
name: filter[]
required: false
schema:
type: array
x-java-sdk-legacy-param: false
items:
type: string
description: >-
A case-sensitive filter on the list. See the [Filter
lists](https://developer.zuora.com/quickstart-api/tutorial/filter-lists/)
section of the Quickstart API Tutorial for detailed
instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the `filter[]` parameter on the related objects such as `filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63`
- in: query
name: page_size
required: false
schema:
type: integer
x-java-sdk-legacy-param: false
minimum: 1
maximum: 99
description: >-
The maximum number of results to return in a single page. If the
specified `page_size` is less than 1 or greater than 99, Zuora will
return a 400 error.
- in: path
name: payment_schedule_id
required: true
schema:
type: string
description: >-
Identifier for the payment schedule. Can be either
`payment_schedule_number` or `payment_schedule_id`
- $ref: '#/components/parameters/zuora-track-id'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/zuora-entity-ids'
- $ref: '#/components/parameters/idempotency-key'
- $ref: '#/components/parameters/accept-encoding'
- $ref: '#/components/parameters/content-encoding'
x-operation-type: post
x-code-samples:
- lang: Curl
label: cURL
source: >-
curl --request POST --url
https://rest.apisandbox.zuora.com/v2/payment_schedules/8ad085e289e27bc80189e44803cb6d4e/cancel
--header 'Content-Type: application/json' --header 'Authorization:
Bearer 2a79d716ffa44c1cb6e45fffc4047b6f' --data '{
"cancel_date": "2023-09-01"
}'
x-group-parameters: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/paymentSchedule'
example:
id: 8ad09e208992481b018993b265472bcb
updated_by_id: 2c92c0946a6dffc0016a7faab604299b
updated_time: '2023-07-27T09:14:46-07:00'
created_by_id: 2c92c0946a6dffc0016a7faab604299b
created_time: '2023-07-26T12:34:49-07:00'
custom_fields:
field__c: custom field value
account_id: 8ad09e20896d5f7f018970bbca5d3508
description: ''
payment_schedule_number: PS-00000008
run_hour: 0
total_amount: 0
next_payment_date: ''
recent_payment_date: ''
state: canceled
total_payments_errored: 0
total_payments_processed: 0
prepayment: false
headers:
ratelimit-limit:
description: >-
The request limit quota for the time window closest to
exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: string
ratelimit-remaining:
description: >-
The number of requests remaining in the time window closest to
quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
ratelimit-reset:
description: >-
The number of seconds until the quota resets for the time window
closest to quota exhaustion. See [rate
limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/#rate-limits)
for more information.
schema:
type: number
zuora-request-id:
description: Zuora’s internal identifier for this request.
schema:
type: string
zuora-track-id:
description: >-
A user-supplied identifier for this request. If you supply a
`zuora-track-id` as a request header, Zuora returns the
`zuora-track-id` as a response header.
schema:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Request
example:
type: bad_request
errors:
- code: invalid_parameter
parameter: currency
message: '''currency'' length must be between 3 and 3'
retryable: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
example:
type: unauthorized
errors: []
retryable: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Not Found
example:
type: not_found
errors:
- code: resource_not_found
parameter: id
message: >-
Resource 2c92c0f974e9737a0175034cc0cc10c could not be
found
retryable: false
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Method Not Allowed
example:
type: method_not_allowed
retryable: false
errors: []
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Too Many Requests
example:
type: too_many_requests
errors: []
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal Server Error
example:
type: internal_server_error
errors: []
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad Gateway
example:
type: bad_gateway
errors: []
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Service Unavailable
example:
type: service_unavailable
errors: []
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
description: Gateway Timeout
example:
type: gateway_timeout
errors: []
servers:
- description: US Developer & Central Sandbox (incl. Test Drive)
url: https://rest.test.zuora.com/v2
- description: US API Sandbox Cloud 1
url: https://rest.sandbox.na.zuora.com/v2
- description: US API Sandbox Cloud 2
url: https://rest.apisandbox.zuora.com/v2
- description: US Production Cloud 1
url: https://rest.na.zuora.com/v2
- description: US Production Cloud 2
url: https://rest.zuora.com/v2
- description: EU Developer & Central Sandbox
url: https://rest.test.eu.zuora.com/v2
- description: EU API Sandbox
url: https://rest.sandbox.eu.zuora.com/v2
- description: EU Production
url: https://rest.eu.zuora.com/v2
security:
- bearerAuth: []
tags:
- name: Accounts
description: >-
This object represents your customer. It lets you create recurring charges
and track payments that belong to the same customer.
- name: Contacts
description: Contacts represent your customer's contact details.
- name: Custom Objects
description: >-
Zuora Custom Objects provides a uniform custom data service for you to
manage custom objects in Zuora. Those custom data is stored on Zuora's
platform and can be used to extend the data model to accommodate your
specific use cases.
- name: Orders
description: >-
The Orders operations enable you to create or make modifications to
subscriptions in a batch.
- name: Order Line Items
description: >-
Order line items are non subscription based items created by an order,
representing transactional charges such as one-time fees, physical goods,
or professional service charges that are not sold as subscription
services. <br/> With the Order Line Items feature
enabled, you have the ability to launch non-subscription and unified
monetization business models in Zuora, in addition to subscription
business models.
- name: Subscriptions
description: >-
Subscriptions allow you to charge a customer on a recurring basis, such as
a monthly charge or a charge based on usage and must be associated with an
Account object. Subscriptions can also include one-time charges, such as
service activation fees.
- name: Subscription Plans
description: >-
A subscription plan is part of a subscription or an amendment to a
subscription, and it comes from a price. Like a product and its plans, a
subscription can have one or more subscription plans. Subscription
plans represent a price or a collection of prices for a service you sell.
An individual subscription plan contains all prices specific to a
particular subscription.
- name: Subscription Items
description: >-
A subscription item is a part of a subscription plan, and it comes from a
price.
- name: Fulfillments
description: >-
Fulfillments are subordinate objects attached to their related order line
item. You can manage the entire order line item lifecycle through
fulfillments in the following ways: <br/>
<ul><li>Create and attach fulfillments to an order line item to track the
shipment or return status.</li> <li>Trigger billing based on
the fulfillment state and generate billing documents based on the
fulfillments accordingly. </li> <li>Create and attach
fulfillment items to a fulfillment to keep track of all the assets in your
system.</li></ul>
- name: Fulfillment Items
description: >-
Fulfillment items are subordinate objects attached to their related
fulfillment.
- name: Bill Runs
description: >-
Bill runs automatically create invoices for your customers on a set
schedule, as well as create invoices for your customers, as needed. A bill
run gathers information from one or more customer accounts and generates
invoices for those accounts. The operations in this
section allows you to create, update, get, or delete bill runs.
- name: Bill Run Previews
description: >-
The Bill Run Previews operations allow you to generates a preview of
future billing document items for a batch of accounts through a bill
run. A bill run preivew job also generates a downloadable CSV
file containing a preview of invoice item data for the customer account
batch.
- name: Billing Documents
description: ' **Note: The API operations in this section have been deprecated.** <p> Billing Documents represent your customer''s invoices, credit memos and debit memos. Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription. They contain invoice items, and proration adjustments that may be caused by changes to a subscription. If your invoice is configured to be charged automatically, Zuora automatically finalizes your invoice and attempts payment otherwise Zuora will email the invoice to your customer and await payment. Any customer credit memos may be applied before determining the amount due for the invoice (i.e., the amount that will be charged).</p>'
- name: Billing Document Items
description: ' **The API operations in this section have been deprecated.** <p> Billing document items represent each item in your customer''s invoices, credit memos, or debit memos.</p>'
- name: Invoices
description: >-
Invoices are statements of amounts owed by a customer and are usually
generated by a [bill
run](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Create_bill_runs).
For more information about invoices, see
[Invoices](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/IA_Invoices/A1_Invoice_Introduction).
- name: Credit Memos
description: >-
Credit memos reduce invoice and account balances. By applying one or more
credit memos to invoices with positive balances, you can reduce the
invoice balances in the same way as applying a payment to an invoice. For
more information about credit memos, see [Credit and debit
memos](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/B_Credit_and_Debit_Memos).
- name: Debit Memos
description: >-
Debit memos increase the amount a customer owes. Debit memos can be used
to correct undercharging on an invoice or to levy ad hoc charges outside
the context of a subscription. Just like an invoice, debit memo balances
can be settled by applying either a payment or a credit memo. For more
information about debit memos, see [Credit and debit
memos](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/B_Credit_and_Debit_Memos).
- name: Taxation Items
description: >-
The TaxationItem object is used to add a tax amount to an invoice
item. Z-Tax and third-party tax engines such as Avalara or
Connect tax engine can create TaxationItem objects. Before you use the
Taxation Item object, you have to configure Z-Tax, Avalara, or Connect tax
engine, as the object's fields rely on the values you create during the
configuration process.
- name: Usage Records
description: >-
The operations in this section allows you to create, update, get, or
delete usage records. Zuora expects no more than 25
million usage records per month. If you want to go over this limit,
contact your Zuora account manager for further consultation.
- name: Payment Methods
description: >-
Payment methods represent your customer's payment instruments. They can be
used to collect payments or saved to Account objects to store instrument
details for future payments.
**Important**: The `type` field in the request body schema of the [Create a payment method](https://developer.zuora.com/other-api/quickstart-api/operation/createPaymentMethod/) operation enumerates the supported payment methods. Not all payment gateways support all these payment method types. Check <a href="https://knowledgecenter.zuora.com/Zuora_Payments/Zuora_Payments_overview/D_Supported_payment_methods" target="_blank">Supported payment methods</a> to check the supported payment methods for each gateway.
If you need to create payment methods outside the scope of this operaton, you have to use the [Create a payment method](https://developer.zuora.com/v1-api-reference/api/operation/POST_PaymentMethods/) operation of the v1 API instead of the Quickstart API.
We do not plan to add additional payment methods to the Quickstart API.
Any new payment methods will only be available through the v1 API and Zuora client libraries.
- name: Payments
description: >-
Payments represents a customer payment. The Payment object holds all of
the information about a payment, including the payment amount and which
billing documents the payment is applied to.
- name: Payment Runs
description: >-
Payment runs are used to collect payments using electronic payment
methods. Even if a payment was made to an invoice but had an error, if an
invoice has a positive balance and meets all the filter criteria for the
payment run, Zuora will pick up the invoice for processing in the payment
run. <br/> Zuora supports two type of payment runs: ad hoc and
recurring. These are similar to ad hoc and scheduled bill runs
- name: Payment Schedules
description: >-
The Payment Schedules feature enables you to collect a series of payments
following customized timelines and rules. You have the flexibility to
leverage a payment schedule to process either a single payment or multiple
payments. <br/> You can leverage this feature to split
invoice or account balances into several installments, and then
automatically process payments for the installments. Payment schedules can
also be used to collect external payments made for the installments.
Meanwhile, we’ve provided you the capability to easily manage and modify
existing schedules, as well as to manually retry failed payments with
updated configurations.
- name: Payment Schedule Items
description: >-
A payment schedule consists of one or more payment schedule items that can
be picked up by payment runs, which are hourly scheduled by Zuora. Each
payment schedule item will trigger a payment process.
- name: Refunds
description: >-
A refund returns money to a customer. For instance, refunds are used when
a customer cancels service and is no longer your customer. The
Quickstart API allows you to refund payments, update refunds, and get
refunds.
- name: Products
description: >-
Products describe the specific goods or services you offer to your
customers and help you track inventory or provisioning. They should be
used in conjunction with Plans and Prices to configure pricing.
- name: Plans
description: >-
Plans are collections of Prices which define the unit cost, currency, and
(optional) billing cycle for both recurring and one-time purchases of
Products. While Products help you track inventory or provisioning, plans
and prices help you track payment terms. Different physical goods or
levels of service should be represented by products, and pricing and
billing cycle options should be represented by prices grouped together in
a plan. This approach lets you change prices without having to change your
provisioning scheme. For example, you might have a single ''Gold'' product
that has prices for $100/month, $1000/year, and $50 once with the
alternative billing cycle and pricing options each represented by a
different plan and the recurring and one-time prices represented by
different prices.
- name: Prices
description: >-
Prices define the unit cost, currency, and (optional) billing cycle for
both recurring and one-time purchases of products. Products help you track
inventory or provisioning, and plans and prices help you track payment
terms. Different physical goods or levels of service should be represented
by products, and pricing options should be represented by prices. This
approach lets you change prices without having to change your provisioning
scheme. For example, you might have a single ''Gold'' product that has
prices for $100/month, $1000/year, and $50 once.
- name: Workflows
description: >-
Run a specified workflow. In the request body, you can include parameters
that you want to pass to the workflow. For the parameters to be recognized
and picked up by tasks in the workflow, you need to define the parameters
first.
- name: Query Runs
description: >-
The Query Runs operations allow you to create, retrieve, or cancel a Data
Query job run.
x-tagGroups:
- name: PRODUCTS
tags:
- Products
- Plans
- Prices
- name: CUSTOMER ACCOUNTS
tags:
- Accounts
- Contacts
- name: ORDERS AND SUBSCRIPTIONS
tags:
- Orders
- Order Line Items
- Subscriptions
- Subscription Plans
- Subscription Items
- Fulfillments
- Fulfillment Items
- name: BILLING DOCUMENTS
tags:
- Invoices
- Credit Memos
- Debit Memos
- name: BILL RUNS
tags:
- Bill Runs
- Bill Run Previews
- name: TAX
tags:
- Taxation Items
- name: USAGE
tags:
- Usage Records
- name: PAYMENTS
tags:
- Payment Methods
- Payments
- Payment Runs
- Payment Schedules
- Payment Schedule Items
- Refunds
- name: PLATFORM
tags:
- Custom Objects
- Query Runs
- Workflows
- name: DEPRECATED
tags:
- Billing Documents
- Billing Document Items