common 0.7.41

The Flow Commerce REST API provides full access to the global ecommerce platform.

Resources

No resources

Headers

No headers

Imports

No imports

Enums

attribute_data_type

Used to tag attributes with a data type so they are properly validated.

Name Value Description
boolean boolean

Boolean true/false data type

decimal decimal

Decimal datatype without size or precision restrictions. Commonly used for currency values.

string string

Unvalidated string of characters.

availability_status

Name Value Description
enabled enabled

disabled disabled

calendar

Name Value Description
weekdays weekdays

Mon - Fri

everyday everyday

7 days per week

capability

Name Value Description
crossdock crossdock

change_type

Name Value Description
insert insert

update update

delete delete

currency_label_formatter

A currency label formatter accepts a price label and updates it according to a set of rules.

Name Value Description
strip_trailing_zeros strip_trailing_zeros

If a price ends in ‘.00’ or ‘,00’, we remove the cents and just display the price as a whole number. e.g. ‘A$100.00’ becomes ‘A$100’

currency_symbol_format

The currency symbol format controls which set of currency symbols we use when displaying currencies

Name Value Description
narrow narrow

The narrow format refers to the Unicode Common Locale Data Repository (CLDR) ‘narrow’ symbols (e.g. ‘$’ for CAD and AUD)

primary primary

The primary format refers to the Unicode Common Locale Data Repository (CLDR) ‘primary’ symbols (e.g. ‘CA$’ for CAD and ‘A$’ for AUD)

day_of_week

Name Value Description
sunday sunday

monday monday

tuesday tuesday

wednesday wednesday

thursday thursday

friday friday

saturday saturday

delivered_duty

Name Value Description
paid paid

Delivered Duty Paid (DDP). See https://en.wikipedia.org/wiki/Incoterms for more information

unpaid unpaid

Delivered Duty Unpaid (DDU). See https://en.wikipedia.org/wiki/Incoterms for more information

discount_item_discount_location

Name Value Description
item item

Display item discount at the item level.

order order

Display item discount at the order level.

discount_target

Name Value Description
item item

Discount is targeted to an item.

shipping shipping

Discount is targeting to shipping. Only applicable if the discount is provided at the order level.

environment

Name Value Description
sandbox sandbox

In sandbox, no external services (e.g. orders, payments, logistics) will generate real transactions

production production

In production, all external services are live and will generate real transactions

exception_type

Name Value Description
open open

closed closed

holiday_calendar

Name Value Description
us_bank_holidays us_bank_holidays

jewish_holidays jewish_holidays

included_levy_key

The key of each possible localized price note is defined here.

Name Value Description
duty duty

vat vat

vat_and_duty vat_and_duty

none none

incoterm

International Commercial Terms are a series of pre-defined commercial terms published by the International Chamber of Commerce (ICC) relating to international commercial law.

Name Value Description
EXW EXW

Ex Works (named place of delivery)

FCA FCA

Free Carrier (named place of delivery)

CPT CPT

Carriage Paid To (named place of destination)

CIP CIP

Carriage and Insurance Paid to (named place of destination)

DAT DAT

Delivered At Terminal (named terminal at port or place of destination)

DAP DAP

Delivered At Place (named place of destination)

DDP DDP

Delivered Duty Paid (named place of destination)

FAS FAS

Free Alongside Ship (named port of shipment)

FOB FOB

Free on Board (named port of shipment)

CFR CFR

Cost and Freight (named port of destination)

CIF CIF

Cost, Insurance & Freight (named port of destination)

DAF DAF

Delivered at Frontier (named place of delivery)

DES DES

Delivered Ex Ship

DEQ DEQ

Delivered Ex Quay (named port of delivery)

DDU DDU

Delivered Duty Unpaid (named place of destination)

input_specification_type

Name Value Description
text text

number number

margin_type

Either a fixed or percent adjustment applied to some amount.

Name Value Description
fixed fixed

A fixed amount to add, e.g 2.5 would add an absolute margin of 2.5 in the base currency of your item.

percent percent

A percent of the base cost to add, e.g. 1.2 would represent a 1.2% increase.

measurement_system

Name Value Description
imperial imperial

metric metric

merchant_of_record

The merchant of record enum defines who is merchant of record for a particular transaction - either Flow is serving as the merchant of record or the organization is serving as merchant of record.

Name Value Description
flow flow

organization organization

order_merchant_of_record

The order merchant of record defines who is merchant of record for a particular order. The value will be ‘mixed’ if you support split payments and the merchant of record differed across the individual payment transactions.

Name Value Description
flow flow

organization organization

mixed mixed

price_book_status

Name Value Description
draft draft

published published

archived archived

role

A user’s role within an organization

Name Value Description
admin admin

member member

rounding_method

Direction to round localized price

Name Value Description
up up

Round up to the specified rounding.value

down down

Round down to the specified rounding.value

nearest nearest

Round to the nearest specified rounding.value. If equidistant, will round up.

rounding_type

Rounding type determines the rule used to enforce rounding. Common rules will ensure that the final price ends w/ a given number (e.g. ends with .95) or is a multiple of some number (multiples of 5 or 10 are common).

Name Value Description
pattern pattern

Rounds a value to an amount ending with a pattern, e.g. an amount ending in ‘.99’.

multiple multiple

Rounds a value to an amount that is the multiple of a value, e.g. rounding to the nearest 5 would ensure that the resulting number ends in either 0 or 5.

schedule_exception_status

Name Value Description
Open Open

Closed Closed

sort_direction

Name Value Description
ascending ascending

descending descending

unit_of_measurement

Defines the units of measurement that we support. As units are added, we conform with the standard units provided by jscience as part of JSR 363 - see http://jscience.org/api/javax/measure/unit/SI.html and http://jscience.org/api/javax/measure/unit/NonSI.html

Name Value Description
millimeter millimeter

Equivalent to MILLI(METRE).

centimeter centimeter

Equivalent to CENTI(METRE).

inch inch

A unit of length equal to 0.0254 m (standard name in).

foot foot

A unit of length equal to 0.3048 m (standard name ft).

cubic_inch cubic_inch

A unit of volume equal to one cubic inch (in³).

cubic_meter cubic_meter

The metric unit for volume quantities (m³).

gram gram

A unit of mass equal to 1 / 1000 kilogram (standard name g).

kilogram kilogram

The base unit for mass quantities (kg).

meter meter

The base unit for length quantities (m).

ounce ounce

A unit of mass equal to 1 / 16 POUND (standard name oz).

pound pound

A unit of mass equal to 453.59237 grams (avoirdupois pound, standard name lb).

unit_of_time

Defines the units of time that we support

Name Value Description
year year

month month

week week

day day

hour hour

minute minute

user_status

The status of the user account. Valid transitions are from pending -> active, active -> inactive, inactive -> active

Name Value Description
pending pending

Represents a new user account that is pending approval

active active

Represents an active user account - can authenticate with this account

inactive inactive

Represents an inactive user account - can no longer authenticate with this account

value_added_service

Name Value Description
Hazardous Material Hazardous Material

See https://en.wikipedia.org/wiki/ORM-D

visibility

Name Value Description
public public

private private

Models

address

Example Json: Minimal | Full

Defines structured fields for address to be used in user/form input. Either text or the structured input needs to be present.

Field Type Required? Default Description Annotations
text string No -

Full text version of address

personal_data

streets [string] No -

Array for street line 1, street line 2, etc., in order

personal_data

street_number string No -

The specific street number, if available.

personal_data

city string No -

province string No -

postal string No -

country string No -

The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: CAN

latitude string No -

personal_data

longitude string No -

personal_data

billing_address

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
name name No -

The name of the customer associated with the billing address

personal_data

streets [string] No -

Array for street line 1, street line 2, etc., in order

personal_data

city string No -

province string No -

postal string No -

country string No -

The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: CAN

company string No -

Business entity or organization name of this contact

personal_data

catalog_item_reference

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
id string Yes -

number string Yes -

catalog_item_summary

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
number string Yes -

name string Yes -

attributes map[string] Yes -

Minimum: 0

contact

Example Json: Minimal | Full

Defines structured fields for a contact person. Typically used for specifying contact person for an account, shipment, or organization representative

Field Type Required? Default Description Annotations
name name Yes -

Personal information of point-of-contact

personal_data

company string No -

Business entity or organization name of this contact

personal_data

email string No -

personal_data

phone string No -

personal_data

customer

Example Json: Minimal | Full

A customer represents the actual person purchasing from you. This information is needed primarily to support logistics (delivery to this person), fraud management (verification of who the person is), and reporting. We also recommend including your customer number whenever possible as doing so will allow Flow to link up transactions for this customer making customer service easier.

Field Type Required? Default Description Annotations
name name Yes -

personal_data

number string No -

personal_data

consumer

phone string No -

Customer phone number. Useful for both fraud and order delivery.

personal_data

consumer

email string No -

Customer email address. Useful for fraud.

personal_data

consumer

address billing_address No -

personal_data

invoice customer_invoice No -

Customer invoice details.

customer_form

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
name name No -

personal_data

number string No -

personal_data

consumer

phone string No -

Customer phone number. Useful for both fraud and order delivery.

personal_data

consumer

email string No -

Customer email address. Useful for fraud.

personal_data

consumer

address billing_address No -

personal_data

invoice customer_invoice No -

Customer invoice details.

customer_invoice

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
address billing_address No -

The address to be used for invoicing and harmonization.

datetime_range

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
from date-time-iso8601 Yes -

to date-time-iso8601 Yes -

dimension

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
depth measurement No -

diameter measurement No -

length measurement No -

weight measurement No -

width measurement No -

dimensions

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
product dimension No -

packaging dimension No -

discount_form

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
offer discount_offer Yes -

target discount_target Yes item

Indicates the target of the discount.

label string No -

Label to display (e.g. the discount code). Discounts with the same label represent aggregated offers.

location discount_item_discount_location Yes order

Indicates the location of the item discount on the order.

discount_offer_fixed

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
money money Yes -

discount_offer_percent

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
percent decimal Yes -

Minimum: 0
Maximum: 100

discounts_form

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
discounts [discount_form] Yes -

duration

Example Json: Minimal | Full

Represents a duration of time.

Field Type Required? Default Description Annotations
unit unit_of_time Yes -

value long Yes -

Minimum: 0

exception

Example Json: Minimal | Full

Represents an exception to the schedule of a center.

Field Type Required? Default Description Annotations
type exception_type Yes -

datetime_range datetime_range Yes -

Range for the holiday. For single-day holidays, from and to should just be the same.

Example: 2021/12/24 12:00 am to 2021/12/25 11:59 pm

experience_summary

Example Json: Minimal | Full

Some important fields related to experiences used in various APIs

Field Type Required? Default Description Annotations
id string Yes -

key string Yes -

name string Yes -

country string No -

ISO 3166 3 currency code as defined in https://api.flow.io/reference/countries

Example: CAN

currency string No -

The ISO 4217-3 code for the currency. Case insensitive. See https://api.flow.io/reference/currencies

Example: CAD

language string No -

ISO 639 2 language code as defined in https://api.flow.io/reference/languages

Example: en

included_levies

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
key included_levy_key Yes -

label string Yes -

The label for the included levies that can be displayed as a tooltip on the product detail page.

input_form

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
values map[string] No -

input_form_specification

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
inputs [input_specification] No -

limitations input_specification_limitations No -

input_specification

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
type input_specification_type Yes -

name string Yes -

display_text string No -

Text to display for this input.

input_specification_limitation_max

Example Json: Minimal | Full

Represents the maximum number of accepted inputs

Field Type Required? Default Description Annotations
max long Yes -

input_specification_limitations

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
limitations [input_specification_limitation] No -

item_reference

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
number string Yes -

line_item

Example Json: Minimal | Full

Line items represent the items a consumer is purchasing, including additional information to complete the transaction. Note that you may pass in as many line items as you like - including repeating item numbers across line items.

Field Type Required? Default Description Annotations
number string Yes -

quantity long Yes -

Minimum: 1

price money Yes -

The price of this item for this order. If not specified, we will use the item price from the experience. Note that this price represents the price of a single line item - the total price to the consumer will be quantity * price.

attributes map[string] Yes -

A set of key/value pairs that you can attach to the order. It can be useful for storing additional information about the charge in a structured format.

center string No -

Optional center key associated with this item. Used for orders and quotes to specify where to ship an item from. If not specified, Flow will infer based on inventory setup.

discount money No -

The total discount, if any, to apply to this line item. Note that the discount is the total discount to apply regardless of the quantity here

line_item_form

Example Json: Minimal | Full

Line items represent the items a consumer is purchasing, including additional information to complete the transaction. Note that you may pass in as many line items as you like - including repeating item numbers across line items.

Field Type Required? Default Description Annotations
number string Yes -

quantity long Yes -

Minimum: 1

shipment_estimate datetime_range No -

For items that may not immediately ship out from the origin because of different models of inventory (e.g. drop-ship, sell-first), this is a way for a client to communicate when the items can ship out. This will be used to calculate delivery option windows.

price money No -

The price of this item for this order. If not specified, we will use the item price from the experience

attributes map[string] No -

A set of key/value pairs that you can attach to the order. It can be useful for storing additional information about the charge in a structured format.

center string No -

Optional center key associated with this item. Used for orders and quotes to specify where to ship an item from. If not specified, Flow will infer based on inventory setup.

discount money No -

The total discount, if any, to apply to this line item. Note that the discount is the total discount to apply regardless of the quantity here

discounts discounts_form No -

The discounts, if any, to apply to this line item. Note that the discount is the total discount to apply regardless of the quantity here

margin

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
type margin_type Yes -

value decimal Yes -

measurement

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
value string Yes -

Example: 12.23

units unit_of_measurement Yes -

Example: inch

merchant_of_record_entity

Example Json: Minimal | Full

The merchant of record entity provides the legal name and address of the specific Flow entity serving as merchant of record.

Field Type Required? Default Description Annotations
organization organization_reference Yes -

Example: flow

name string Yes -

Example: Flow Commerce Limited

vat merchant_of_record_entity_registration Yes -

streets [string] Yes -

Street Address Lines

city string Yes -

province string No -

postal string No -

country string Yes -

The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: IRL

phone string No -

Primary customer service phone number for this entity

email string No -

Primary customer service email address for this entity

merchant_of_record_entity_registration

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
number string Yes -

In Europe, this is the VAT registration number for the entity. In the US, this is the EIN.

country string Yes -

The country in which this registration number is defined. The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: CAN

money

Example Json: Minimal | Full

Money represents an amount in a given currency

Field Type Required? Default Description Annotations
amount double Yes -

currency string Yes -

ISO 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

money_with_base

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
currency string Yes -

Iso 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

amount double Yes -

base money Yes -

money_with_optional_base

Example Json: Minimal | Full

Used to migrate older models to have a base value, without breaking compatibility

Field Type Required? Default Description Annotations
currency string Yes -

Iso 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

amount double Yes -

base money No -

name

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
first string No -

personal_data

last string No -

personal_data

organization

Example Json: Minimal | Full

Represents a single organization in the system, and what environment it is currently operating in.

Field Type Required? Default Description Annotations
id string Yes -

name string Yes -

environment environment Yes -

parent organization_reference No -

When creating an organization in the test environment, it is linked to your production organization. This allows you to have as many test organizations as you like.

defaults organization_defaults No -

Always present. Marked optional for backwards compatibility.

created_at date-time-iso8601 No -

organization_defaults

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
country string Yes -

The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: CAN

base_currency string Yes -

ISO 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

language string Yes -

ISO 639 2 language code as defined in https://api.flow.io/reference/languages

Example: en

locale string Yes -

The locale id as defined in https://api.flow.io/reference/locales

Example: fr-CA

timezone string Yes -

The name of the timezone as defined in https://api.flow.io/reference/timezones

Example: America/New_York

organization_reference

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
id string Yes -

organization_summary

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
id string Yes -

name string Yes -

partner_reference

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
id string Yes -

price

Example Json: Minimal | Full

Represents an amount-currency pair for a basic price

Field Type Required? Default Description Annotations
amount double Yes -

currency string Yes -

ISO 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

label string Yes -

price_form

Example Json: Minimal | Full

Amount-currency paid for a basic price to be used in model forms, before a price label is created. Label in the main price model is created by the implementing api.

Field Type Required? Default Description Annotations
amount double Yes -

currency string Yes -

ISO 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

price_with_base

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
currency string Yes -

Iso 4217 3 currency code as defined in https://api.flow.io/reference/currencies

Example: CAD

amount double Yes -

label string Yes -

The localized label of the amount and currency

Example: $125.00 CAD

base price No -

rounding

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
type rounding_type Yes -

method rounding_method Yes -

value decimal Yes -

schedule

Example Json: Minimal | Full

Represents operating calendar and holidays of a center

Field Type Required? Default Description Annotations
calendar calendar No -

Operating calendar used by origin center for shipment, if available. If not provided, assume they are never open.

Example: Weekdays, 7 days, etc.

holiday holiday_calendar Yes -

Standard holiday set to respect for this schedule

Example: US bank holidays

exception [exception] Yes -

Holiday calendar used by origin center for shipment, if available.

Example: Memorial Day, Independence Day, etc.

cutoff string No -

Daily cutoff time for shipment fulfillment at origin center, if available. 24-hour time

Example: 16:45

min_lead_time long No -

Optional number of days a center takes to make a shipment

max_lead_time long No -

Optional number of days a center takes to make a shipment

user

Example Json: Minimal | Full

Represents a single user in the system

Field Type Required? Default Description Annotations
id string Yes -

email string No -

If known, the user’s primary email address. While in most common cases, we expect users to have email addresses, there are edge cases where it is useful to allow a user to NOT have an email address. For example, users interacting solely from mobile devices, guest user accounts, initial onboarding where email is not known, etc. We think by starting off with an optional primary email address we can support these use cases with very little implementation cost.

personal_data

name name Yes -

The user’s name.

personal_data

status user_status Yes active

Only active users are authorized to login and interact with the Flow platform.

user_reference

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
id string Yes -

zone

Example Json: Minimal | Full
Field Type Required? Default Description Annotations
postals [string] No -

Group of postal code prefixes included in this zone

Example: [M9P,M9R,M9V,M9W]

provinces [string] No -

Group of provinces included in this zone. Values should in ISO 3166-2 province code format.

Example: [AB, ON]

country string Yes -

The ISO 3166-3 country code. Case insensitive. See https://api.flow.io/reference/countries

Example: CAN

Unions

discount_offer

  • Type discriminator: discriminator
Type Discriminator Value Example Json Description
discount_offer_fixed discount_offer_fixed Minimal | Full

discount_offer_percent discount_offer_percent Minimal | Full

expandable_organization

  • Type discriminator: discriminator
Type Discriminator Value Example Json Description
organization organization Minimal | Full

organization_reference organization_reference Minimal | Full

expandable_user

  • Type discriminator: discriminator
Type Discriminator Value Example Json Description
user user Minimal | Full

user_reference user_reference Minimal | Full

input_specification_limitation

  • Type discriminator: discriminator
Type Discriminator Value Example Json Description
input_specification_limitation_max input_specification_limitation_max Minimal | Full

Annotations

personal_data

Identifies a field that contains Personal Data, as defined by GDPR. By default, any field marked with this annotation will be kept for 1 year and will be purgeable upon request provided there are no incomplete business activities associated with it.

consumer

Identifies a field that contains data about a consumer [as opposed to an employee of Flow, an organization or a partner].