Primitives
This page lists all Commerce primitives and their definitions.
Product
A product is a container for all catalog definitions of a product that Atlassian is making available to the market.
Examples of products:
- Jira Software
- Confluence
- Jira Service Management
- Statuspage
- Gliffy
Offering
An offering represents a packaging of a product that'll result in an entitlement. It affects billing, distribution, and feature settings.
Examples of offerings:
- For the Jira Software product:
- Free
- Standard
- Premium
- For the Statuspage product:
- Private Trial
- Public Trial
Pricing plan
Pricing plans define how paid offerings are priced and charged for, and result in subscriptions. A pricing plan is where pricing, currency, and billing cycle options are configured for an offering.
Transaction account
A transaction account is a container that groups together all transaction-related entities. It helps a person who’s signing up for offerings organize their billing entities with Atlassian. It's used to support individuals and companies (direct and partners).
A transaction account (TxA) has:
- A bill-to party
- One or more payment methods
- (Optional) One or more ship-to addresses
- (Optional) Partner status
A transaction account is initially created with just a billing admin identifier, which must be a valid Atlassian user. The entities described above can be created using separate API calls, with the transaction account ID passed in request headers. This delayed construction of the transaction account entity allows for Commerce consumers to have greater flexibility during their end-user signup flows.
Users who have created an Atlassian account may have security roles created for one or more transaction accounts.
Invoice
An invoice is an itemized statement of amounts owed by a customer as a result of using one or more products. An invoice is issued by an invoice group and inherits all information defined for the invoice group or transaction account. An invoice will compute and add tax for items. An invoice will also reflect payment collection status.
Invoice group
An invoice group is a container that allows you to manage invoices.
An invoice is issued by an invoice group with all pending invoice requests for each invoicing cycle. If there are no pending invoice requests, then no invoice will be issued. The invoice header will reflect the data defined for the invoice group. The header contains a name, a currency, a payment method ID, an invoicing cycle, a ship-to ID, and, optionally, a list of email recipients. The name is a free text field.
The payment method ID references the payment method that should be used for collecting money owed for each invoice created by the invoice group. If the payment method ID is empty, the default payment method of the transaction account is used.
The invoicing cycle controls how often invoices are issued for pending requests. It currently defaults to one day, which means that each day the invoice group will issue a new invoice for any pending invoice requests. The payment method will be charged the amount defined in the invoice (tax included) at the end of the invoicing cycle.
The ship-to information references the ship-to of the invoicing group. If not specified, the transaction account bill-to will be used as the ship-to.
Examples:
- For an individual customer, create one invoice group for each payment method with an empty ship-to
- For a partner, each end customer has at least one invoice group
Payment method
A payment method is a payment instrument used for collecting money owed for an invoice. It has a currency, a source type, an ID, and terms information.
A payment method can be marked as the default payment method of the transaction account.
The two supported source types are credit card and deferred.
Credit cards are stored directly in the payment gateway, in a PCI-compliant manner, and added to transaction accounts using a reference ID.
A deferred payment is a credit limit issued by Atlassian to the customer. Payments for invoices that have a deferred payment method happen outside of Commerce systems. A deferred payment method can be added for a transaction account only by designated Atlassian staff, since granting a credit limit is subject to a credit check. Ensuring the credit limit isn't breached is currently managed by restricting self-service transactions that use deferred payment. The terms information drives the due date of invoices issued for this payment method.
Examples:
- A VISA credit card with the Stripe ID
card_1G5qStIqu7CGM8lBnkhf6QlTthat has the last four digits 4242, expires on 11/2022, issued in the US - A deferred payment method with invoices due in 30 days
Bill-to party
The bill-to party is a container for billing information of the party that owns the transaction account. It has a name, a postal address (the country field should be ISO 3166-1 alpha-2-compliant), and an optional tax ID and special price eligibility. The postal address is used for tax calculation for invoices. Special price eligibility is an enum of pricing plan types for which orders should be allowed.
The tax ID is a country-issued ID for the legal entity that is represented in the bill-to. If the bill-to isn't a legal entity, the tax ID should be empty. The issuing country is the country of the postal address. Different countries will have different labels for their tax ID: VAT ID in the EU and UK, ABN in Australia, and FEIN in the US.
The tax ID will also drive tax exemptions.
Ship-to party
The ship-to party is a container for billing information of the party that uses entitlements. All entitlements for which a particular invoice is generated should be used by the same ship-to party.
A ship-to party has a name, a postal address, and optionally a tax ID and special price eligibility. The postal address will contribute to tax calculation for invoices. Special price eligibility is an enum of pricing plan types for which orders should be allowed.
The tax ID is a country-issued ID for the legal entity that is represented in the ship-to. If the ship-to isn't a legal entity, the tax ID should be empty. The issuing country is the country of the postal address. Different countries will have different labels for their tax ID: VAT ID in the EU and UK, ABN in Australia, and FEIN in the US.
The tax ID will also drive tax exemptions.
Order
An order is an entity representing a user's intent to create, amend, or delete a contract to provide the enumerated service from a billing perspective. Once accepted, it becomes a mutually binding contract to provide the enumerated service. Note that orders don't encapsulate any provisioning details and don't orchestrate provisioning on their own.
An order needs to capture the entire future billing state of the product being ordered.
When placing an order, the caller needs to specify:
- The transaction account that will own the order
- The invoice group for generating the invoices as a result of the order
- The offering being ordered
- The pricing plan from the offering if the offering is a paid one
- The ordered quantity
- Any promotions to be applied
- The current entitlement ID and version in case the order is an amendment
After submitting, the order is validated for eligibility and Commerce constraints.
As part of order processing, the time when the contract will become effective is computed and stamped on the order. The created or modified Commerce entitlements are also stamped on the order.
Examples:
- In the transaction account
TxA1, James Bond orders a Statuspage Private Trial for a quantity of 1 to be invoiced under the invoice groupIG1 - The order becomes effective immediately and the entitlement
E-001is created on version 1 - In the transaction account
TxA1, James Bond orders an upgrade ofE-001on version 1 to Statuspage Private Enterprise paid monthly on the government agency GBP plan for a quantity of 2 to be invoiced under the Invoice GroupIG2, which references a deferred payment method - The order becomes effective immediately and the entitlement
E-001is created on version 2
Entitlement
An entitlement is an instantiated offering from the product catalog. All the features that are specified in the offering entitlement template are copied in the entitlement. An entitlement carries the quantities that are charged in its variables.
Examples:
- A Confluence Standard instance
- A Jira Software Premium instance
Quotes
A quote is a legally non-binding offer of products or services typically sent to a customer for consideration before making a buying decision. Quotes typically include a listing of products or services and relevant prices and expire after a period of time.
Examples:
- A quote to create a termed subscription of one year for a Jira Container with Jira Software and Zephyr App added to the container
- A quote to amend an entitlement to increase the charge quantity of a line item from 100 to 200 users
Quote object states
A quote can exist in the following states through its lifecycle: draft, open, stale, accepted, and cancelled. The transitions between the states are depicted in the following diagram:
Rate this page: