orderCreate

orderCreate is used by all Connected integrations to create orders in Marketplacer.

Key Information

Use-Case

orderCreate is used to generate orders in Marketplacer. This is most usually the case with Connected Integrations, i.e. when an existing eCommerce frontend is used to checkout and capture payment details, orderCreate is then called to place the order in Marketplacer with the relevant detail.

Further Points of Note

As well as the points of note listed below, the following article covers the use of orderCreate in much more detail.

  • There has to be a sufficient stock holding for each variant you wish to purchase - this is the countOnHand attribute on each variant object
    • You cannot over-order, i.e quantity > countOnHand
    • You cannot pre-order
  • The unit of currency for both cost and postage objects is the lowest denominated unit of currency configured for the marketplace, e.g.:
    • US / Australian Dollars: Unit of currency would be cents
    • GBP Pound: Unit of currency would be pence
    • Euro: Unit of currency would be cents
  • We require a “whole cents unit price”.
    • E.g. if you supplied 10830 for the amount with a quantity of 4, this equates to an individual line item price of 2707.5 cents, (fractions of a cent are not permissible)
    • In the above case the individual line item price is rounded up to 2708, resulting in total line item amount of 10832 cents ($108.32)
  • If you choose to supply a value for tax you have to do so for both cost and postage objects you cannot just specify for one
  • If you choose to supply values for tax for 1 line item (for both cost and postage objects), you have to supply tax values for all line items on the order
  • Multiple line items from different Sellers can be added, Markerplacer will workout the “order-split” or invoice creation automatically
  • adjustments of types FEE and PROMOTION can be applied using orderCreate however the reader should be aware of the following:
    • Promotions (PROMOTION) can only be applied on Line Items (LineItemInput) and not via the Invoice (InvoiceInput)
    • Custom Fees (FEE) can only be applied on the Invoice (InvoiceInput) and not via Line Items (LineItemInput)

Availability

  • Operator API: Yes
  • Seller API: No - sellers cannot create orders

Example

mutation createAnOrder {
  orderCreate(
    input: {
      order: {
        firstName: "Les"
        surname: "Jackson"
        phone: "0405555555"
        emailAddress: "someone@email.com"
        address: {
          address: "146 Buckhurst Street"
          city: "Melbourne"
          country: { code: "AU" }
          postcode: "3000"
          state: { name: "Victoria" }
        }
      }
      lineItems: [
        {
          variantId: "VmFyaWFudC04NDkzOA=="
          quantity: 1
          cost: { amount: 1000 }
          postage: { amount: 100 }
        }
      ]
    }
  ) {
    order {
      id
      legacyId
      totalCents
      invoices {
        nodes {
          id
          legacyId
        }
      }
    }
    errors {
      field
      messages
    }
  }
}

Arguments

NameType
inputOrderCreateMutationInput

Response

Returns OrderCreateMutationPayload


Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
200Field orderCreate doesn’t exist on type “Mutation”Most likely you are not passing a valid Operator key (only Operators can create orders)
200Cannot be blank (address.address)1st address line cannot be blank
200Cannot be blank (address.country_id)A valid country code must be supplied
200Cannot be blank (address.postcode)A zip or post code must be supplied
200Cannot be blank (address.state_id)State not supplied or name invalid
200Expected one of invoices or lineItems: received neitherYou need to supply either InvoiceInput or LineItemInput.
200Argument ‘variantId’ on InputObject ‘LineItemInput’ is required. Expected type ID!A valid variant Id is required to place an order (the variant Id in this scenario represents the product line item you are purchasing)
200Argument ‘quantity’ on InputObject ‘LineItemInput’ is required. Expected type Int!Along with the variant Id you need to specify a quantity
200Expected lineItem to specify cost.You must supply a total cost for all ordered variants (line items)
200Expected lineItem to specify tax on postage.When you have specified tax with lineItem cost you need to supply a tax value with postage
200Expected lineItem to specify tax on cost.When you have specified tax with postage you need to supply a tax value with lineItem cost
200must be greater than 0 (invoices.line_items.quantity)You cannot create an order and specify the line item quantity as 0
200Validation failed: Count on hand must be greater than or equal to 0You have tried to place an order when the line item quantity specified is greater than the stock holding (countOnHand) for that variant
200order with same external id already existsIf you specify (optional) externalIds with orderCreate, those Ids need to be unique for each call.

Further Reading