Skip to main content

Carts, Tags, and Items

OmniCart is designed to accept multiple items in a payment request by default so you can think of each payment request as a shopping cart, even if it contains a single item. Items in a cart can be marked with tags.

Items in Carts​

The code to the right is an example of a simple request with only the mandatory properties for the initiate cart request.

Each cart must have a unique cartId that is generated on your side. The currency property is mandatory and applied to the entire cart.

The pegasus object here is an item identifier that contains the mandatory amount property (see Amounts section for more information on handling amounts).

{
  "cartId": "6f891edb-1e1f-48bb-b042-2cb790a0f402",
  "currency": "XAU",
  "items": [
    {
      "pegasus": {
        "amount": 250
      }
    }
  ]
}
Please, note

All item identifiers have to be uploaded to OmniCart in the Merchant Panel to be available for purchase as each cart initiation request must contain at least one existing item identifier.

An item is not necessarily an actual consumable product. It can be, for example, a donation, a one time purchase (such as a premium tier), or a temporary access to your resource (e.g., a year subscription).

A cart may contain items of any type.

In the example to the right the items array contains several item identifiers: donation, milk, and premiumAccess. This code implies these item identifiers were previously registered in the Merchant Panel .

  "items": [
    {
      "lich": {
        "amount": 600
        },
      "wight": {
        "amount": 230
        },
      "vampire": {
        "amount": 500
        }
      }
  ]

Tags​

You can mark cart items with tags to group these items, batch apply payment or timer settings (batch settings are explained in the section below), or for any other reason you may have.

An item can be assigned only one tag.

OmniCart accepts all tags provided they have a valid format. If you really want it, you can use a different tag or set of tags for each initiate cart request. Since tags are generated on your side, you are in charge of their consistency.

In the request snippet to the right, the mage and naga items are assigned the tower tag. The beholder item is marked with the dungeon tag and the nomad item doesn't have a tag at all.

After a cart is initiated, you can utilize tags to retrieve cart item statuses, cancel, capture, or refund items by calling the corresponding API methods (see also Payment Lifecycle for more information on item statuses).

Tags can also be redefined or reassigned by calling the modify method — this option is described in detail in the Modify section of this documentation.

    "items": [
      {
        "mage": {
          "tag": "tower",
          "amount": 450
        }
      },
      {
        "naga": {
          "tag": "tower",
          "amount": 1600
        }
      },
      {
        "nomad": {
          "amount": 200
        }
      },
      {
        "beholder": {
          "tag": "dungeon",
          "amount": 280
        }
      },
    ]

Batch Settings and Overrides​

OmniCart allows you to batch apply certain payment settings and timer settings to items in a cart. These settings can be applied to the entire cart or by tag. The tag settings override the cart settings. The settings of a specific item, in turn, override all parent settings, even if this item is marked with a defined tag. Think of it as of nested structure or hierarchical inheritance, cart being the top level.

note

An item may or may not be assigned a tag. If an item is not assigned a tag, its settings still override the cart settings.

Take a look at the code examples to the right. Cart level settings define only the amountMode and capture properties.

Tag settings inherit amountMode, override the capture property, and define additional capture settings.

Item settings override the parent amountMode and autoAction properties and add the amountModifier property for that specific item. Other settings are inherited.

Legend
  //undefined
  //newly defined
  //inherited from parent
  //overridden by child
      "amountMode": "declared",
      "amountModifier": null,
      "capture": false,
      "captureSettings": {
        "autoAction": null,
        "value": null
      },
      "enableTimer": null,
      "timer": {
        "triggerEvent": null,
        "value": null
      }
Please, note

In an actual request you can define as many tags as you want or assign them to items without defining.

  • If you define a tag and do not assign it to any item, the initiate cart request will be accepted by OmniCart despite the fact that the defined tag has no practical effect on the request result.
  • Similarly, if you assign an item with a tag that is not defined, it is not considered an error.