Record Purchase

Feature: Purchases

Editions: Cloud, Corporate*

The purchaseAdd mutation endpoint can be used to record purchases in POS. Purchases include sales invoices that are created in a third party system such as an ERP or ecommerce site.

POS uses purchase records to enable several features. These features include generating loyalty points, and enabling analytics and reports.

POS automatically creates purchase records for sales that are processed through the Kensium Register and Kensium Shopping Cart. This API enables clients to record sales from other systems.

This API requires the AddPurchase permission.

Of note:

• Purchase transaction IDs are not validated for duplicates. The caller should ensure that transaction requests are not duplicated.
• Loyalty points are potentially generated only if you supply information that identifies a customer that has a POS membership. In order of priority, this can be: the POS member ID, the Windows Register customer ID, or the customer email address.

Examples

Minimal Example

Create a purchase record with the minimum required fields:

mutation MyMutation {
  purchaseAdd(
    add: {
      transactionId: "TRANS00002",
      storeCode: "DALLAS",
      purchasedOn: "2021-09-15T04:50:00",
      payAmount: "1.99",
      saleDiscountAmount: "0",
      itemDiscountAmount: "0",
      subTotal: "1.99",
      refundAmount: "0",
      taxAmount: "0",
      lineItems: [
        {
        lineNumber: 1,
        sku: "GUM001",
        isRefund: false,
        unitPrice: "1.99",
        extPrice: "1.99",
        itemDiscountAmount: "0",
        saleDiscountAmount: "0",
        quantity: "1",
        uom: "EA"
        }
      ]
    }    
  )
  {
    id
  }
}

Complete Example

This example records a purchase with two line items, and all fields populated:

mutation MyMutation {
  purchaseAdd(
    add: {
      transactionId: "TRANS00003",
      storeCode: "DALLAS",
      purchasedOn: "2021-09-15T04:50:00",
      payAmount: "5.79",
      saleDiscountAmount: "0.06",
      itemDiscountAmount: "0.12",
      subTotal: "1.81",
      refundAmount: "0",
      taxAmount: "0",
      channel: "WEB",
      memberId: "C000000212",
      orderType: "SI",
      payMethod: "CASH",
      lineItems: [
        {
          lineNumber: 1,
          sku: "GUM001",
          isRefund: false,
          unitPrice: "1.99",
          extPrice: "1.99",
          itemDiscountAmount: "0.12",
          saleDiscountAmount: "0",
          quantity: "1",
          uom: "EA",
          name: "Gum small pack",
          vendor: "WRIGLEYS",
          productPriceClass: "SML",
          unitCost: "0.98",
          refundTransactionId: null,
          refundLineNumber: null
        },
        {
          lineNumber: 2,
          sku: "LAYS002",
          isRefund: false,
          unitPrice: "3.98",
          extPrice: "3.98",
          itemDiscountAmount: "0",
          saleDiscountAmount: "0.06",
          quantity: "1",
          uom: "EA",
          name: "Lays Chips 13 oz",
          vendor: "LAYS",
          productPriceClass: "SML",
          unitCost: "1.28",
          refundTransactionId: null,
          refundLineNumber: null
        }
      ]
    }    
  )
  {
    id
  }
}

Note the distinction between sale and item discounts:

• Item discounts are applied directly against an item.
• Sale discounts are applied to the sale as a whole, but are apportioned to each item (usually pro-rated to the item amount).

Refund Example

A simple example to show a refunded item is:

mutation MyMutation {
  purchaseAdd(
    add: {
      transactionId: "TRANS00003",
      storeCode: "DALLAS",
      purchasedOn: "2021-09-15T04:50:00",
      payAmount: "-3.98",
      saleDiscountAmount: "-0.06",
      itemDiscountAmount: "0",
      subTotal: "-3.98",
      refundAmount: "3.98",
      taxAmount: "0",
      channel: "WEB",
      memberId: "C000000212",
      orderType: "SI",
      payMethod: "CASH",
      lineItems: [
        {
          lineNumber: 1,
          sku: "LAYS002",
          isRefund: true,
          unitPrice: "3.98",
          extPrice: "-3.98",
          itemDiscountAmount: "0",
          saleDiscountAmount: "-0.06",
          quantity: "-1",
          uom: "EA",
          name: "Lays Chips 13 oz",
          vendor: "LAYS",
          productPriceClass: "SML",
          unitCost: "1.28",
          refundTransactionId: "TRANS00003",
          refundLineNumber: 2
        }
      ]
    }    
  )
  {
    id
  }
}

Note the sign of each field; most amount fields are negative for refunded items. See the GraphQL field reference for full details.