> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Return all refunds
> Return all refunds.
## OpenAPI
````yaml /marketONE/Amdocs_Media-Commerce-Gateway.yaml get /transactions/{transactionId}/refunds
openapi: 3.0.1
info:
title: ULM Storefront Gateway
description: >
These APIs allow clients to perform purchase and payment method management;
OTT service and billing authorization operations. These APIs require a user
access token. The APIs are thus aware of and therefore authorized by this
ULM context (a user's entitlements as defined in the ULM platform service).
The following tracing headers can be used for all APIs:
X-B3-TraceId: The TraceId indicates the overall ID of the trace. Every span
in a trace shares this ID. The X-B3-TraceId header is encoded as 32 or 16
lower-hex characters. For example, a 128-bit TraceId header might look like
463ac35c9f6413ad48485a3953bb6124.
X-B3-SpanId: The SpanId is 64-bit in length and indicates the position of
the current operation in the trace tree. The value should not be
interpreted; it may or may not be derived from the value of the TraceId. The
X-B3-SpanId header is encoded as 16 lower-hex characters. For example, a
SpanId header might look like a2fb4a1d1a96d312. Unless propagating only the
Sampling State, the X-B3-SpanId header is required.
X-B3-ParentSpanId: The ParentSpanId is 64-bit in length and indicates the
position of the parent operation in the trace tree. When the span is the
root of the trace tree, there is no ParentSpanId. The X-B3-ParentSpanId
header may be present on a child span and must be absent on the root span.
It is encoded as 16 lower-hex characters. For example, a ParentSpanId header
might look like 0020000000000001.
The APIs can be accessed via a tenant specific domain or the
X-Aggregator-Code header must specify a MarketONE organization code:
X-Aggregator-Code: The aggregator organization code. Organization code must
be provided either via HTTP header or query parameter. If both are provided,
HTTP header will be used.
aggregatorCode: The aggregator organization code. Organization code must be
provided either via HTTP header or query parameter. If both are provided,
HTTP header will be used.
version: Latest
servers:
- url: https://default.ulm.stg.m1amdocs.io/storefront
security:
- bearerAuth: []
paths:
/transactions/{transactionId}/refunds:
get:
tags:
- transactions
summary: Return all refunds
description: Return all refunds.
operationId: getAllTransactionRefunds
parameters:
- name: transactionId
in: path
description: The SLM ID of the transaction.
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: '#/components/schemas/Refund'
- type: object
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Model400Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Model401Error'
'403':
description: Authorization Error
content:
application/json:
schema:
$ref: '#/components/schemas/Model403Error'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Model404Error'
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Model500Error'
security:
- bearerAuth:
- storefront
components:
schemas:
Refund:
type: object
properties:
object:
type: string
description: Value is “Refund”
enum:
- Refund
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
created:
type: string
description: The date/time at which the refund was requested.
transaction:
$ref: '#/components/schemas/Transaction'
refund_items:
type: array
description: >-
For item-level refunds, specifies the transaction items to refund
with details.
items:
$ref: '#/components/schemas/RefundItem'
refund_distribution_strategy:
type: string
description: >-
Defines strategy for distributing refund amount across the original
TransactionItems. Default is None.
enum:
- None
- SpecifiedItems
- RemainingBalance
amount:
type: number
description: >-
Amount of the refund. Must be positive (non-zero) and less than or
equal to the as-yet-un-refunded balance of the specified
transaction. Ignored if refundItems are specified.
amount_includes_tax:
type: boolean
description: whether the amount is tax-inclusive or -exclusive
currency:
type: string
description: >-
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this transaction; defaults to USD.
metadata:
$ref: '#/components/schemas/METADATA'
reference_string:
type: string
description: Read-only. Information provided by payment processor.
note:
type: string
description: Free-form CSP-specified notes about refund.
token_action:
type: string
description: Action to take with any Tokens paid on transaction. Default None.
enum:
- CancelNegativeBalance
- CancelZeroBalance
- None
credit:
$ref: '#/components/schemas/Credit'
status:
type: string
description: Processing status of refund.
enum:
- Complete
- Failed
- Processing
- Reported
description: >-
The Refund object provides a way to reverse a charge, refunding money to
the customer. You can create, and retrieve individual Refunds; as well
as list all existing Refunds. Refunds require a transaction – a refund
can only be executed against an existing, successfully captured
transaction. Refunds can be issued for any valid amount (in the currency
of the original transaction) up to the as-yet un-refunded balance of the
original transaction. You can issue any number of refunds on a given
transaction (until it has been fully refunded).
Model400Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- invalid-request
message:
type: string
validationErrors:
type: array
items:
$ref: '#/components/schemas/Model400ValError'
Model401Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- authentication-required
- invalid-api-key
- api-key-not-found
message:
type: string
Model403Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- forbidden
- access-denied
- invalid-scope
- not-permitted
message:
type: string
Model404Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- not-found
message:
type: string
Model500Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- server-error
message:
type: string
ID:
maxLength: 256
type: string
description: A unique identifier.
VID:
maxLength: 128
type: string
description: >-
A Globally Unique Identifier (GUID) for this object. This value is
generated by MarketONE.
Transaction:
type: object
properties:
object:
type: string
description: Value is “Transaction”
enum:
- Transaction
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
created:
type: string
description: The time this transaction was initiated.
amount:
type: number
description: >-
The net amount of the charge presented by this transaction, as a
decimal. Must be positive (zero allowed).
original_amount:
type: number
description: >-
Used with a partial payment; this read-only field reflects the
original amount of the transaction, as a decimal.
currency:
type: string
description: >-
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this transaction
division_number:
type: string
description: >-
The CSP’s division, reporting or processing group as defined with
their payment processor.
previous_id:
type: string
description: The identifier of a previous version of this transaction.
account:
$ref: '#/components/schemas/Account'
source_payment_method:
$ref: '#/components/schemas/PaymentMethod'
dest_payment_method:
$ref: '#/components/schemas/PaymentMethod'
ecp_transaction_type:
type: string
description: For ECP/ACH-specific types.
enum:
- All
- Inbound
- InboundOutbound
- NA
- Outbound
- Transfer
status_log:
$ref: '#/components/schemas/Transaction_status_log'
payment_processor:
type: string
description: The payment processor used for processing this transaction.
payment_processor_transaction_id:
type: string
description: The identifier assigned to the Transaction by the Payment Processor.
shipping_address:
$ref: '#/components/schemas/Address'
metadata:
$ref: '#/components/schemas/METADATA'
items:
$ref: '#/components/schemas/TransactionItems'
affiliate:
type: string
description: >-
CSP’s ID for the channel or affiliate associated with this
transaction, if any. This is a free-form string of 128 characters or
less.
sub_affiliate:
type: string
description: >-
Affiliate ID for a more granular channel component (see
CSP_affiliate_id).
user_agent:
type: string
description: >-
Information on the source of the transaction, such as the Customer’s
user-agent string, as presented by the browser.
preferred_notification_language:
type: string
description: >-
ISO language code string. Transaction value will override any
language setting on the account.
source_mac_address:
type: string
description: >-
MAC address of the customer (primarily intended for ISP usage), may
be left blank if unavailable or inappropriate.
source_ip:
type: string
description: End-customer’s source IP associated with this transaction.
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for this
transaction.
sales_tax_address:
$ref: '#/components/schemas/Address'
verification_code:
type: string
description: >-
External verification response (e.g. Verified by Visa, MasterCard
SecureCode).
subscription_sequence:
type: integer
description: >-
The subscription’s billing cycle for which this transaction collects
funds. As a zero-based index, this indicates the renewal number.
billing_plan_sequence:
type: integer
description: >-
The billing cycle for which this transaction collects funds - as
counted as a zero-based index from the last billing plan change for
the associated subscription.
mandate:
$ref: '#/components/schemas/Mandate'
original_billing_date:
type: string
description: >-
The original scheduled billing date associated with the billing for
which this transaction collects funds. For an initial attempt, this
is the same as the transaction date; for a retry transaction this is
the original attempt date.
billing_attempt:
type: integer
description: >-
The zero-based index counting the number of transaction attempts
this particular transaction represents in collecting for given
subscription billing cycle.
subscription:
$ref: '#/components/schemas/Subscription'
score:
type: integer
description: The chargeback and fraud risk score generated by Vindicia.
score_calculated:
type: string
description: The datetime the score was calculated.
score_calculated_orig:
type: string
description: The datetime the score was originally calculated.
score_codes:
type: array
description: The reason codes justifying the risk score.
items:
$ref: '#/components/schemas/ScoreCode'
distance_ip_ba:
type: number
description: The distance from the IP Address to the Billing Address.
avs_code:
type: string
description: AVS Code
cvn_code:
type: string
description: CVN Code.
cvn_checked:
type: boolean
description: Shows if the CVN was checked for this transaction.
policy:
type: object
additionalProperties:
type: string
properties:
key:
type: string
value:
type: string
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information.
to_be_captured:
type: boolean
description: Indicator of whether the transaction is currently pending capture.
description: >-
The Transaction object provides a way to charge a customer. You can
create one-time transactions, retrieve individual transactions, fetch
individual transactions, and list all Transactions for a given account
or subscription. Posting with a new Transaction creates a new one-time
Transaction object. If “to_be_captured” is false, the request will
trigger an authorization attempt (based on the provided payment method’s
authorization process). If successfully authorized, a subsequent post to
the transaction’s actions/capture endpoint will capture the authorized
transaction. If you post a new transaction with “to_be_captured” true,
it will authorize and immediately capture the transaction if successful.
To refund transactions, use the refunds endpoint.
RefundItem:
type: object
properties:
transaction_item_index_number:
type: number
description: >-
Sequence number assigned upon creation to a TransactionItem by
Vindicia. Either the transactionItemIndexNumber, or the sku, must be
specified for each RefundItem.
sku:
type: string
description: >-
SKU on the original transaction line item (sku need not be passed in
if the transactionItemIndexNumber is passed in). If the sku is
passed in, and can be used to uniquely identify the transaction
item, it will be used, otherwise an error will be returned.
description:
type: string
description: >-
Output only. A description of the TransactionItem, which will be
filled in by Vindicia from line item description on the original
Transaction.
amount:
type: number
description: >-
Amount of the requested refund for this item, in the currency of the
overall transaction. This amount must not exceed the original
TransactionItem amount, minus any discounts and minus the sum of all
prior refunds against this item. This field may be left blank if the
taxOnly field is set to true.
tax_only:
type: boolean
description: >-
If this is true, the amount parameter is ignored and the refund
amount will be the total of the as-yet unrefunded taxes for this
item.
taxes:
type: array
description: >-
Read-only array to list the taxes from the original TransactionItem
that are being refunded.
items:
$ref: '#/components/schemas/TaxItem'
METADATA:
type: object
additionalProperties:
type: string
properties:
key:
type: string
value:
type: string
description: >-
A set of key/value pairs that you can attach to an object. Useful for
storing additional information.
Credit:
type: object
properties:
object:
type: string
description: Value is “Credit”
enum:
- Credit
token_amounts:
type: array
description: Tokens granted
items:
$ref: '#/components/schemas/TokenAmount'
currency_amounts:
type: array
description: Currency credits granted
items:
$ref: '#/components/schemas/CurrencyAmount'
description: >-
The Credit object represents a service credit granted to an account or
subscription, taking the form of either currency, token, or time
amounts.
Model400ValError:
required:
- code
type: object
properties:
code:
type: string
message:
type: string
Account:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
metadata:
$ref: '#/components/schemas/METADATA'
paymentMethods:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
PaymentMethod:
type: object
properties:
id:
type: string
createdDate:
type: string
merchantAcceptedPayment:
$ref: '#/components/schemas/MerchantAcceptedPayment'
creditCard:
$ref: '#/components/schemas/CreditCard'
carrierBilling:
$ref: '#/components/schemas/CarrierBilling'
debitCard:
$ref: '#/components/schemas/DirectDebit'
externalBilling:
$ref: '#/components/schemas/ExternalBilling'
metadata:
$ref: '#/components/schemas/METADATA'
primary:
type: boolean
active:
type: boolean
currency:
type: string
type:
type: string
description: Type of payment method.
enum:
- CarrierBilling
- ExternalBilling
- MerchantAcceptedPayment
- CreditCard
- DebitCard
Transaction_status_log:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
description: >-
A log of various TransactionStatus entries associated with this
transaction.
items:
$ref: '#/components/schemas/TransactionStatus'
Address:
type: object
properties:
object:
type: string
description: Value is “Address”
enum:
- Address
vid:
$ref: '#/components/schemas/VID'
name:
type: string
description: The name of the person or contact associated with this address.
line1:
type: string
description: Address Line 1
line2:
type: string
description: Address Line 2
line3:
type: string
description: Address Line 3
city:
type: string
county:
type: string
district:
type: string
description: State, Province, or District
postal_code:
type: string
country:
type: string
phone:
type: string
fax:
type: string
latitude:
type: number
longitude:
type: number
description: The Address object represents a physical or mailing address.
TransactionItems:
type: object
properties:
object:
type: string
description: Value is “List”
data:
type: array
items:
$ref: '#/components/schemas/TransactionItem'
total_count:
type: integer
description: Integer count of the number of items in the returned list.
Mandate:
type: object
properties:
object:
type: string
description: Value is “Mandate”
enum:
- Mandate
created:
type: string
description: The date/time at which the mandate was recorded into Vindicia.
identifier:
type: string
description: Externally provided unique identifier for the Mandate (agreement).
status:
type: string
description: Current Mandate status.
enum:
- Active
- Cancelled
- Expired
- Failed
- Pending
description: >-
The mandates object represents the end-custom approval for a one-time or
recurring billing using their provided bank account details. A common
requirement for UK and SEPA direct debit payment methods.
Subscription:
required:
- account
- id
- items
- object
- status
type: object
properties:
object:
type: string
description: Value is “Subscription”.
enum:
- Subscription
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
created:
type: string
description: The date/time at which the subscription was requested.
account:
$ref: '#/components/schemas/Account'
billing_plan:
$ref: '#/components/schemas/BillingPlan'
payment_method:
$ref: '#/components/schemas/PaymentMethod'
currency:
type: string
description: >-
An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code.
A subscription’s charges must be in a single currency.description
string An optional customer-facing identifier or descriptive name
for the subscription
description:
type: string
description: >-
An optional customer-facing identifier or descriptive name for the
subscription
status:
type: string
description: >-
The status of the subscription from a service and entitlement
perspective.
enum:
- Pending Activation
- Active
- Paused
- Pending Pause
- Pending Resume
- Pending Cancel
- Cancelled
- Expired
- Processing
- Deleted
- Dryrun
- Unknown
- Upgraded
- Legacy Suspended
- Bogus AutoBill Status
billing_state:
type: string
description: The financial state of the subscription.
enum:
- Free/Trial
- Billing Completed
- Failed To Collect
- Free Period
- Paused
- Good Standing
- Grace Period
- In Retry
- Legacy Unknown BillingState
- Overdue
- Pending Acceptance
- Terminated
- Unbilled
- Unknown
- Unusable PaymentMethod
- Pending Resume
- Pending Pause
- Bogus BillingState
starts:
type: string
description: The date/time the subscription starts service.
ends:
type: string
description: The date/time the subscription ends service.
entitled_through:
type: string
description: >-
The date/time to which the subscription will entitle service if no
further payments are made – a “paid thru” date based on billing
schedule and grace period.
items:
$ref: '#/components/schemas/Subscription_items'
source_ip:
type: string
description: Optional source IP Address at sign-up.
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions from this subscription.
billing_day:
type: integer
description: >-
The day of the month on which the subscription is (typically)
billed. Often called an “anniversary date.”
minimum_commitment:
type: integer
description: >-
Number of billing cycles customer is obligated to maintain the
subscription. Cancelling before this time requires CSP to “force”
cancellation.
affiliate:
type: string
description: >-
Affiliate or channel identifier, if any, under which the
subscription was submitted.
sub_affiliate:
type: string
description: A more granular or subordinate affiliate identifier.
notify_on_transition:
type: boolean
description: >-
Indicates whether to send an expiration or trial-end email
notification using the days-in-advance configuration in the Billing
Plan.
most_recent_billing:
$ref: '#/components/schemas/Transaction'
most_recent_refunds:
$ref: '#/components/schemas/Subscription_most_recent_refunds'
next_billing:
$ref: '#/components/schemas/Transaction'
metadata:
$ref: '#/components/schemas/METADATA'
credit:
type: object
description: Credit balance of the subscription.
statement_format:
type: string
description: >-
Instructions for if/how to include the invoice statement for this
subscription. Values can be Attachment, DoNotSend,Inline
enum:
- Attachment
- DoNotSend
- Inline
invoice_terms:
type: integer
description: >-
Net Terms (in days); after this many days from a billing, the
invoice will be considered delinquent.
statement_offset:
type: integer
description: Days before scheduled billing to deliver the statement.
statement_template:
type: string
description: Template to use for statement generation.
billing_plan_campaign_code:
type: string
description: >-
The Campaign code redeemed on this AutoBill against the price of the
Billing Plan. To apply a Campaign, use this field to pass in a valid
Coupon or Promotion code. Note This data member will not be
returned.
billing_plan_campaign_id:
type: string
description: >-
The unique identifier for a Campaign applied to this AutoBill’s
BillingPlan. This is a read-only field returned by Vindicia for
informational purposes. Values sent in with a SOAP call will be
ignored. Read only.
unknown_starts:
type: boolean
description: Used to create a Subscription Pending Activation.
balance:
type: number
mandate:
$ref: '#/components/schemas/Mandate'
cancel_reason:
$ref: '#/components/schemas/CancelReason'
policy:
type: object
description: The policy object governing Subscription behavior.
description: >-
Subscriptions allow you to bill an Account over time and/or on a
recurring basis. A subscription ties an Account to a particular billing
plan and set of purchased products (subscription items) you’ve created.
The API allows you to create, update and amend/modify your
subscriptions.
ScoreCode:
type: object
properties:
object:
type: string
description: Value is “ScoreCode”
enum:
- ScoreCode
id:
type: string
description: A Vindicia-specified unique ID.
description:
type: string
description: String description of the rule, e.g. “PRIOR_CB_IN_VERTICAL”
TaxItem:
type: object
properties:
object:
type: string
description: Value is “TaxItem”
jurisdiction:
type: string
description: Tax jurisdiction
name:
type: string
description: Tax description
amount:
type: number
description: Currency amount of assessed tax
external_tax_name:
type: string
external_tax_category:
type: string
external_jurisdiction_name:
type: string
tax_rate:
type: number
description: And individual tax assessed for a specified jurisdiction.
TokenAmount:
type: object
properties:
object:
type: string
enum:
- TokenAmount
token:
$ref: '#/components/schemas/Token'
amount:
type: integer
description: The balance of tokens in the grant.
source:
type: string
description: >-
The TokenAmount object represents the token-based credit detail
associated with a particular grant of token credits.
CurrencyAmount:
type: object
properties:
object:
type: string
description: Value is “CurrencyAmount”
enum:
- CurrencyAmount
vid:
$ref: '#/components/schemas/VID'
currency:
type: string
description: An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code.
amount:
type: number
description: The currency amount of the credit.
metadata:
$ref: '#/components/schemas/METADATA'
sort_value:
type: integer
description: Order of precedence value.
description:
type: string
description: Text provided upon credit grant.
reason:
type: string
description: Text provided upon credit grant.
granted_by_cashbox:
type: boolean
granted:
type: string
description: The date and time the credit was originally granted.
account:
$ref: '#/components/schemas/Account'
subscription:
$ref: '#/components/schemas/Subscription'
description: >-
The CurrencyAmount object represents the currency credit detail
associated with a particular grant of currency credits.
MerchantAcceptedPayment:
type: object
properties:
amount:
type: number
currency:
type: string
created:
type: string
paymentType:
type: string
account:
type: string
lastDigits:
type: string
CreditCard:
type: object
properties:
lastDigits:
type: string
expirationDate:
type: string
CarrierBilling:
type: object
properties:
object:
type: string
description: Value is "CarrierBilling"
enum:
- CarrierBilling
phone_number:
$ref: '#/components/schemas/PhoneNumber'
encoded_phone_number:
type: string
description: >-
Read Only. The payment provider-encoded phone number used in the
Transaction.
carrier:
type: string
description: >-
The identifier for the carrier, either read from the phone or
entered by the customer.
payment_provider:
$ref: '#/components/schemas/PaymentProvider'
currency:
type: string
description: >-
ISO 4217 Currency Code for either the static_price_inc_salestax, or
the dynamic_target_price. (For dynamic pricing, the customer
currency will be determined by the customer region/countryCode.)
country_code:
type: string
description: ISO 3166-1 alpha-2 Country Code for the customer’s location.
price_criteria:
$ref: '#/components/schemas/PriceCriteria'
account_identifier:
maxLength: 255
type: string
description: Unique billing account identifier from Payment Provider BSS.
carrier_billing_account_identifier_type:
type: string
description: the type of the account_identifier. Enumerated.
example: MSISDN
enum:
- BAN
- MSISDN
customer_identifier:
maxLength: 255
type: string
description: >
Unique MSISDN or other billing account identifier from Payment
Provider's BSS.
example: not yet available - see VIN-26551
customer_identifier_type:
maxLength: 255
type: string
description: >
Identifier for the channel from which the customer_identifier value
originated
example: PoS , Web
validated:
type: string
description: Indicates if the payment method is validated
description: This object defines Telco carrier billing details.
DirectDebit:
type: object
properties:
lastDigits:
type: string
ExternalBilling:
type: object
properties:
billReceiver:
type: string
paymentChannel:
type: string
financialAccount:
type: string
TransactionStatus:
type: object
properties:
object:
type: string
description: Value is “TransactionStatus”
enum:
- TransactionStatus
status:
type: string
description: Status of the Transaction.
enum:
- New
- AuthorizationPending
- AuthorizedPending
- Authorized
- AuthorizedForValidation
- Cancelled
- Captured
- Settled
- Refunded
- Pending
created:
type: string
description: The effective datetime of this status
payment_method_type:
type: string
description: Type of Payment Method (clarifies status).
enum:
- CreditCard
- PayPal
- ECP
- DirectDebit
- Token
- HostedPage
- Boleto
- CSPAcceptedPayment
- CarrierBilling
- Amazon
- Skrill
- ApplePay
vin_avs:
type: string
description: AVS result.
enum:
- FullMatch
- PartialMatch
- NoMatch
- IssuerError
- NoOpinion
- NotSupported
funding_source_balance:
type: number
TransactionItem:
type: object
properties:
object:
type: string
description: Value is “TransactionItem”
enum:
- TransactionItem
sku:
type: string
description: >-
The SKU or unique identifier of the product purchased with this item
(for one-time transactions this is an ad-hoc value.
index_number:
type: integer
description: Sequential index of all items on the transaction.
item_type:
type: string
name:
type: string
description: CSP-provided name or inherited description of the product purchased
subscription_item:
$ref: '#/components/schemas/SubscriptionItem'
price:
type: number
description: unit price of this item
metadata:
$ref: '#/components/schemas/METADATA'
quantity:
type: number
description: >-
The unit quantity for the item; for license-based products this is
the license/seat quantity.
tax_classification:
type: string
description: The tax code or classification applicable to this item.
tokens:
type: array
description: >-
Tokens granted to the account on this transaction for purchasing
this item
items:
$ref: '#/components/schemas/TokenAmount'
campaign_code:
type: string
description: Campaign code redeemed on this TransactionItem.
campaign_id:
type: string
description: The unique identifier for a campaign applied to this item.
campaign_description:
type: string
description: >-
Detailed description of the campaign for the discount on this item,
if there is one.
service_period_starts:
type: string
description: The start date for the period the charge on this item covers.
service_period_ends:
type: string
description: The end date for the period the charge on this item covers.
tax_type:
type: string
description: Fixed Tax definition (read only).
tax:
$ref: '#/components/schemas/TransactionItem_tax'
related_transactions:
type: array
description: >-
List of CSPTransactionIds for all Transactions related to this item.
e.g. For a credit resulting from the removal of an SubscriptionItem,
this will contain the list of all Transactions that originally
billed for the item within the time frame covered by the credit.
items:
type: string
item_refunds:
type: array
description: Detail on item-level refunds applied to this item.
items:
$ref: '#/components/schemas/TransactionItemRefundSummary'
discount:
type: number
description: The total discount amount applied to this item.
subtotal:
type: number
description: The pre-tax (post-discount) subtotal.
total:
type: number
description: The grand total of this item
BillingPlan:
type: object
properties:
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
object:
type: string
description: Value is “BillingPlan”
enum:
- BillingPlan
created:
type: string
description: The date and time the plan was created.
description:
type: string
description: A CSP-specified description of this offering.
status:
type: string
description: >-
CSPs may define whether they want to declare a plan as available to
offer. Values can be Active,Suspended
enum:
- Active
- Suspended
tax_classification:
type: string
description: >-
The tax classification or code to be used with any plan-level
charges.
br_tax_category:
type: string
description: enum(Category)
trial:
$ref: '#/components/schemas/BillingPlanPeriod'
periods:
$ref: '#/components/schemas/BillingPlan_periods'
billing_notification_days:
type: integer
description: >-
Number of days prior to schedule billing at which CashBox will send
email notification.
trial_end_notification_days:
type: integer
description: >-
For the trial period, this replaces billing_notification_days,
indicating the number of days prior to end of a trial to send the
trial end email.
skip_initial_billing_notification:
type: boolean
description: >-
Determines whether to send a billing notification for the initial
period.
end_of_life:
type: string
description: The date after which the plan should not be offered.
metadata:
$ref: '#/components/schemas/METADATA'
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions associated with a subscription using this billing plan.
times_to_run:
type: string
description: >-
The number of times the sequence of Billing Periods should be
repeated. Valid input includes positive integers (Default is null).
entitlements_valid_for:
type: string
description: >-
The length of time for which Entitlements are valid after the last
Billing date (Default is null).
repeat_every:
type: string
description: >-
If a Billing Period set repeats, this value defines the length of
time after the first billing that the set should repeat.
days_before_season_to_bill:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days before a season starts to bill.
days_entitled_before_season:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days customer is entitled before a season starts
days_entitled_after_season:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days after a season ends a customer remains entitled.
entitled_off_season:
type: boolean
description: >-
Optional setting when using a season set to continue entitling
customer between seasons.
used_on_subscriptions:
type: boolean
description: Signifies if Billing Plan has been used on an Active Subscription
grace_period_override:
type: integer
description: >-
Number of days after the billing date when, if payment is not
received, the Subscription is stopped and the customer is
disentitled; overrides the global CSP default setting, if both are
set.
Subscription_items:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/SubscriptionItem'
description: The product-based line items for the subscription.
Subscription_most_recent_refunds:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/Refund'
description: >-
A list of any refunds associated with the Transaction in
most_recent_billing.
CancelReason:
type: object
properties:
reason_code:
type: string
description: >-
The reason code assigned for the cancellation. Can be 15 characters
or fewer.
description:
type: string
description: >-
A description of the reason for the cancellation. Can be up to 255
characters.
Token:
type: object
properties:
object:
type: string
description: Value is “Token”
enum:
- Token
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
description:
type: string
description: Text describing the token type
description: >-
The token object provides a way to offer virtual currencies or track the
balance of a consumable service item.
PhoneNumber:
type: object
properties:
object:
type: string
description: Value is "PhoneNumber"
enum:
- PhoneNumber
phone_type:
type: string
description: >-
Type or Use designation for the phone number. Value can be CS, Fax,
Home, Main, Mobile, Pager, Unspecified, Work
enum:
- CS
- Fax
- Home
- Main
- Mobile
- Pager
- Unspecified
- Work
country_code:
type: string
description: Country Code segment of a phone number.
area_code:
type: string
description: Area Code segment of a phone number.
local_number:
type: string
description: Local segment of a phone number (excluding extension).
extension:
type: string
description: Phone number extension.
raw_input:
type: string
description: Raw, unfiltered data input by customer.
description: >-
The payment providers object represents processor or payment channel
used to transact a particular charge.
PaymentProvider:
type: object
properties:
object:
type: string
description: Value is "PaymentProvider"
enum:
- PaymentProvider
name:
type: string
description: Provider Name
dispute_address:
type: string
description: Contact address for written disputes.
dispute_email:
type: string
description: Contact email for electronic disputes.
dispute_uri:
type: string
description: Contact URL for online disputes.
auth_expiration_days:
type: integer
description: Default expiration timing (days) for un-captured authorizations.
auth_currency_override:
type: string
description: Currency override for Authorizations
metadata:
type: object
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information.
description: >-
The payment providers object represents processor or payment channel
used to transact a particular charge.
PriceCriteria:
type: object
properties:
object:
type: string
description: Value is "PriceCriteria"
enum:
- PriceCriteria
payment_provider:
$ref: '#/components/schemas/PaymentProvider'
currency:
type: string
description: >-
ISO 4217 Currency Code for for either the static_price_inc_salestax,
or the dynamic_target_price Overrides CarrierBilling.currency.
country_code:
type: string
description: >-
ISO 3166-1 alpha-2 countryCode for customer location. Overrides
CarrierBilling.countryCode.
price_point_deviation_policy:
type: string
description: >-
The price deviation policy for dynamic price selection. Value can be
HiOnly, HiPreferred, LowOnly, LowPreferred, NearestNoPreference
enum:
- HiOnly
- HiPreferred
- LowOnly
- LowPreferred
- NearestNoPreference
dynamic_price_mode:
type: string
description: >-
Specifies which price point element is matched by the dynamic
pricing algorithm. Values can be PayoutGross, PayoutNet, Price
enum:
- PayoutGross
- PayoutNet
- Price
merchant_service_identifier:
type: string
description: Service identifier for Payment Provider/Merchant.
sub_merchant_identifier:
type: string
description: Optional identifier of sub-merchant associated with Transaction.
description:
type: string
description: ''
fwd_url:
type: string
description: >-
Overrides both the successful transaction forward-to URL and the
failed transaction forward-to URL.
static_selection_row_ref:
type: integer
description: Row number identifier in the static product/service price matrix
static_price_inc_sales_tax:
type: string
description: >-
Price including tax (the actual amount the consumer will pay). Used
with Transactions with static ‘exact match’ pricing.
dynamic_deviation:
type: integer
description: >-
The percent deviation (+/- 1000) from the target value that is
acceptable as a price point selection.
dynamic_match:
type: integer
description: >-
The percent deviation (+/- 1000) from the target value that is
classified as an exact match.
dynamic_target_price:
type: string
description: Target price in the specified currency for dynamic pricing.
description: Price Criteria details used with telco carrier billing payment methods.
SubscriptionItem:
required:
- id
- object
- product
type: object
properties:
object:
type: string
description: Value is “SubscriptionItem”
enum:
- SubscriptionItem
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
index:
type: integer
description: Sequential index of all items on the subscription.
product:
$ref: '#/components/schemas/Product'
amount:
type: number
description: The unit price of the item.
currency:
type: string
description: >-
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this item.
rate_plan:
$ref: '#/components/schemas/RatePlan'
metadata:
$ref: '#/components/schemas/METADATA'
quantity:
type: number
description: >-
The unit quantity for the item; for license-based products this is
the license/seat quantity.
token:
$ref: '#/components/schemas/Token'
campaign_code:
type: string
description: Campaign code for discount
cycles:
type: integer
description: >-
The number of billing cycles for which this item should bill (0 =
life of the Subscription)
cycles_remaining:
type: integer
description: >-
If a billing cycle limit is defined, this is the number of billing
cycles left to bill.
created:
type: string
description: The datetime this item was added to the subscription.
ends:
type: string
description: >-
The datetime this item was removed from the subscription (end of
service).
starts:
type: string
description: >-
The datetime this item was effective/started on the subscription
(start of service).
discount_tickets:
type: array
items:
$ref: '#/components/schemas/DiscountTicket'
campaign_id:
type: string
description: Campaign ID for discount
replaces:
type: object
description: SubscriptionItem replaced by this item.
replaced_by:
$ref: '#/components/schemas/SubscriptionItem'
TransactionItem_tax:
type: object
properties:
object:
type: string
description: always List
data:
type: array
items:
$ref: '#/components/schemas/TaxItem'
total_count:
type: integer
description: Integer count of the number of items in the returned list.
description: >-
array to list the individual tax items associated with the corresponding
transactionItem.
TransactionItemRefundSummary:
type: object
properties:
created:
type: string
amount:
type: string
format: decimal
tax:
type: number
tax_only:
type: boolean
refund:
$ref: '#/components/schemas/Refund'
BillingPlanPeriod:
type: object
properties:
object:
type: string
description: Value is “BillingPlanPeriod”
enum:
- BillingPlanPeriod
type:
type: string
description: Unit of time a period describes. Values can be Day,Week,Month,Year
enum:
- Day
- Week
- Month
- Year
quantity:
type: integer
cycles:
type: integer
prices:
$ref: '#/components/schemas/BillingPlan_prices'
BillingPlan_periods:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/BillingPlanPeriod'
Product:
required:
- descriptions
- id
- object
- status
type: object
properties:
object:
type: string
description: Value is “Product”
enum:
- Product
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
created:
type: string
description: The date/time the object was created.
descriptions:
$ref: '#/components/schemas/Product_descriptions'
status:
type: string
description: >-
CSPs may define whether they want to declare a product as available
to offer.
enum:
- Active
- Suspended
tax_classification:
type: string
description: The tax classification or code for this product.
br_tax_category:
type: string
enum:
- Goods
- Services
default_billing_plan:
$ref: '#/components/schemas/BillingPlan'
default_rate_plan:
$ref: '#/components/schemas/RatePlan'
end_of_life:
type: string
description: >-
The date/time after which this product should be treated as
out-of-service.
metadata:
$ref: '#/components/schemas/METADATA'
entitlements:
$ref: '#/components/schemas/Product_entitlements'
inherited_entitlements:
$ref: '#/components/schemas/Product_entitlements'
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions associated with a subscription using this product.
credit_granted:
$ref: '#/components/schemas/Credit'
prices:
$ref: '#/components/schemas/Product_prices'
bundled_products:
$ref: '#/components/schemas/BundledProducts'
description: >-
The Product object represents a unique CSP product, with its own
pricing, description and entitlement assignments. The API allows you to
create, fetch, and update products. You can retrieve individual Product
objects, as well as a list of all.
RatePlan:
type: object
properties:
object:
type: string
description: Value is "RatePlan"
enum:
- RatePlan
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
created:
type: string
description: The date/time the object was created.
format: date-time
description:
type: string
description: Optional description of the rated service offering.
multiply_rated_units_by:
type: string
description: >-
Tier pricing rule. EachRespective charges units “in” that tier at
its price; HighestApplicable is volume pricing, charging at the peak
unit level’s tier for all units. Values can be
EachRespectiveTier,HighestApplicableTier.
enum:
- EachRespectiveTier
- HighestApplicableTier
rated_unit:
$ref: '#/components/schemas/RatedUnit'
tier:
type: array
description: Successive pricing tiers based on unit “from/to” limits
items:
$ref: '#/components/schemas/RatePlanTier'
rounding_decimals:
type: integer
description: >-
Number of digits for rounding; Excel’s ROUND function- 0 = nearest
integer, 2 = 2 decimal places, -2 means = nearest hundred, etc.
format: int32
included_units:
type: integer
description: >-
Number of units included for free; tier 1 starts after included
units have been recorded.
minimum_fee:
type: array
description: Minimum charge per billing period (one price per currency)
items:
$ref: '#/components/schemas/RatePlanPrice'
maximum_fee:
type: array
description: Maximum charge per billing period (one price per currency)
items:
$ref: '#/components/schemas/RatePlanPrice'
rate_plan_model:
type: string
description: >-
Determines pre-paid (licenses or seats billed in advance) or
post-paid (usage recorded throughout the period and billed at period
end. Values can be LicenseBased,UsageBased
enum:
- LicenseBased
- UsageBased
status:
type: string
description: >-
Merchants may define whether they want to declare a plan as
available to offer. Values can be Active,Suspended.
enum:
- Active
- Suspended
has_event_recorded:
type: boolean
description: >-
Read-only field that tells whether this RatePlan has had any events
recorded on it or not.
metadata:
type: string
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information.
description: >-
Rate Plans represents a pre-defined rating schedule - tier-based pricing
for rated products (e.g. usage). Both pre-paid (aka License-based) and
post-paid (metered, aka usage-based) services use pre-defined tiers to
rate recorded events. Rate Plans support flat and per-unit pricing,
volume discounts, standard consumption-based prices, included units with
overage, and maximum/minimum charge limits.
DiscountTicket:
type: object
BillingPlan_prices:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/BillingPlanPrice'
Product_descriptions:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/ProductDescription'
description: Language-specific product/service descriptions
Product_entitlements:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/Entitlement'
description: >-
Entitlements granted by active subscriptions using this product on one
or more subscription items.
Product_prices:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/ProductPrice'
description: >-
Default (i.e. “List”) prices for the product; one price per currency
code. Prices can be overridden at purchase or with modification.
BundledProducts:
type: object
properties:
object:
type: string
description: Must be "List"
enum:
- List
total_count:
type: integer
description: Integer count of the number of items in the returned list.
data:
type: array
items:
$ref: '#/components/schemas/Product'
RatedUnit:
type: object
properties:
name_singular:
type: string
description: Singular name of units.
name_plural:
type: string
description: Plural name of units.
RatePlanTier:
type: object
properties:
name:
type: string
rate_price:
type: array
description: >-
Required. An array of RatePlanPrice objects, which define the Price
(or prices) for this Tier (one price for each currency used).
items:
$ref: '#/components/schemas/RatePlanPrice'
charge_customer:
type: string
description: >-
Can be- FlatFee which defines a stepped pricing structure, in which
the customer is charged the ratePrice per Tier or PerUnit which
defines a graduated pricing structure, in which the customer is
charged the number of units accessed, multiplied by the ratePrice
per Tier.
enum:
- Flatfee
- PerUnit
begins_at_level:
type: integer
description: >-
The number of Units at which this Tier’s pricing structure takes
effect. The number of Units defined for each Tier runs from the
minimum value of the Tier, to one Unit less than the minimum value
of the next higher Tier. Typically the first tier would have
beginsAtLevel = 1. The final, highest tier is unbounded (infinite).
RatePlanPrice:
type: object
properties:
amount:
type: integer
description: Amount
currency:
type: string
description: ISO 4217 Currency Code.
BillingPlanPrice:
type: object
properties:
object:
type: string
description: Value is “BillingPlanPrice”
amount:
type: number
description: price
currency:
type: string
description: >-
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) Currency Code
of price.
price_list_name:
type: string
description: >-
Name of price list containing this price. This is free-form string
of 255 characters or less
token_amount:
$ref: '#/components/schemas/TokenAmount'
ProductDescription:
type: object
properties:
object:
type: string
description: Value is “ProductDescription”
enum:
- ProductDescription
language:
type: string
description: >-
The 2 character ISO language code in which the product description
is written.
description:
maxLength: 256
type: string
description: >-
A description of this product written in language. A free-form
string of less than 256 characters.
Entitlement:
type: object
properties:
object:
type: string
description: Value is “Entitlement”
enum:
- Entitlement
id:
type: string
description: A CSP-specified unique identifier.
description:
type: string
description: The CSP-specified description of the entitled service.
account:
$ref: '#/components/schemas/Account'
subscription:
$ref: '#/components/schemas/Subscription'
billing_plan:
$ref: '#/components/schemas/BillingPlan'
subscription_item:
$ref: '#/components/schemas/SubscriptionItem'
product:
$ref: '#/components/schemas/Product'
starts:
type: string
description: The date/time at which entitlement did or will begin.
ends:
type: string
description: The date/time at which entitlement did or will end.
active:
type: boolean
description: Indicates whether this Entitlement is currently active.
description: >-
The entitlement object represents the services to which a customer is
entitled. Entitlement can reside at the Account (granted directly to the
Customer) or the Subscription level (granted due to purchase or presence
of an active subscription).
ProductPrice:
type: object
properties:
object:
type: string
description: Value is “ProductPrice”
enum:
- ProductPrice
amount:
type: number
description: Value of the currency amount.
currency:
type: string
description: >-
ISO 4217 currency code to be used for this ProductPrice Amount.
Defaults to USD. Note that this is Mutually Exclusive of token
token:
$ref: '#/components/schemas/Token'
securitySchemes:
bearerAuth:
type: oauth2
description: OAuth 2.0 Authentication
flows:
authorizationCode:
authorizationUrl: /oidc/authorize
tokenUrl: /oidc/token
scopes:
storefront: gives access to user api in storefront
storefront-csr: gives access to some csr api in storefront
m2m.storefront.csr.manage: Allows the machine to create and manage(CRUD)
m2m.storefront.csr.read: Allows the machine to read data only
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.