Create a purchase of a product

post

https://api.mobilize.io/v1.1/commerce/purchases

Records a purchase made in an external commerce system and request that it be fulfilled.

The referenced product must exist.

If the user reference resolves to no existing user and an email address is supplied, a user will be created in response to this request.

Fulfillment is processed asynchronously.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

external_ids

array of objects

required

length ≥ 1

Namespaced external identifiers for the purchase in the external commerce system.
They are mapped to it on creation and address it thereafter as {purchase_id}.
An identifier already mapped to another purchase returns 422.

external_ids*

string

required

An arbitrary identifier for a supported resource in Journey by Forj.
Must be unique within its namespace.

namespace

string

required

^[^:/]+$

An arbitrary category for disambiguating External IDs

price

number

required

The price of a single unit, in the major units of currency_code, before discount is applied.

discount

number

Defaults to 0

The discount applied to this purchase, in the major units of currency_code.

currency_code

string

Defaults to USD

ISO 4217 currency code for price and discount.

purchased_at

date-time

required

When the purchase was made in the external commerce system.

entitlement

object

The window during which this purchase entitles the user to the product. Send either date
as null for a purchase that starts immediately or never expires.

A window that has already elapsed is accepted rather than rejected: the entitlement
reports expired and grants no access.

product

object

required

A reference to the course or course bundle being purchased, by either its Journey by Forj
identifier or an External ID. At least one form must be supplied.

Resolution is attempted in order: id first, then the entry in external_ids. A reference
that resolves to nothing purchasable returns 422.

A supplied id is treated as an assertion: if it names nothing purchasable in your
organization the request returns 422 without trying external_ids, rather than recording
the sale against a different product.

An External ID resolves through the mappings on the commerce product, and the course or
course bundle it names must still be active and belong to your organization — an External ID
does not reach a product that id could not.

user

object

required

A reference to the purchasing user, by Journey by Forj identifier, External ID, or email
address. At least one form must be supplied.

Resolution is attempted in order: id, then each entry in external_ids until one resolves,
then email.

A supplied id is treated as an assertion: if it matches no user in your organization the
request returns 422 without trying external_ids or email, rather than attributing the
purchase to a different user or creating a duplicate one.

If no existing user is found and an email was supplied, a user is created. If no existing
user is found and no email was supplied, the request returns 422. Supplying an email
address is what makes creation of a new user possible.

first_name and last_name are used when creating a user and ignored when an existing user
is found; this endpoint never renames an existing user.

201The purchase as created, before asynchronous fulfillment has been applied.

400There was a problem with the request. Refer to the response body for details.

401Credentials were missing from the request or were not valid.

422There was a problem with the request. Refer to the response body for details.

429The rate limit of 100 requests per minute per source IP address was exceeded. Enforced at the load balancer ahead of the application; the response has no body.