Last Updated: 9/22/2021, 7:40:10 AM

# Orders

# Overview

AccelByte Commerce services allow you to keep track of all of the orders your players make. You can view orders made, count how many items have been purchased, and even cancel and refund orders. Some of the main features of Orders include:

  • Order Management enables you to create, fulfill, or refund orders.
  • Order History allows you to see a list of completed orders for all players or for a specific player.
  • Order Receipt is used to generate a receipt for a specific order.

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage orders in the Admin Portal. For a full list of permissions that impact orders management, see the Platform/Commerce tab of the permissions reference

Usage Permission Tag Action
Query user orders ADMIN:NAMESPACE:{namespace}:USER:{userId}:ORDER Read
Get user orders history ADMIN:NAMESPACE:{namespace}:USER:{userId}:ORDER Read
Download user order receipt ADMIN:NAMESPACE:{namespace}:USER:{userId}:ORDER Read
Refund order ADMIN:NAMESPACE:{namespace}:USER:{userId}:ORDER Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# How It Works

Players can order free items, as well as purchase items either by making a payment using funds made available at time of purchase, or by using funds saved in their wallet. See the sequence diagram for each purchase method.

# Order a Free Item

The diagram below shows how players can acquire a free item.

orders

# Purchase an Item Using New Funds

This diagram shows how players can order and pay for an item by making the necessary funds available at time of purchase.

orders

# Purchase an Item Using Funds from Wallet

This diagram shows how players can order and pay for an item using funds stored in their wallet.

orders

# Managing Orders in the Admin Portal

The Admin Portal gives community managers and game admins an easy way to manage players’ orders

# Query a Player’s Order

  1. In the Admin Portal, choose the Publisher Namespace.

    orders

  2. Go to the E-Commerce section and open the Orders menu.

    orders

  3. In the Orders menu, find the desired orders using either the Email, full Order ID, User ID, or Payment Processor Reference ID. You can also filter orders by their Order Status. When you’re done setting your search parameters, press Enter.

    Order Status
    Status Description
    ALL Display all orders, regardless of status.
    Unpaid Unpaid orders occur if there has been an issue with the payment process or when the player did not proceed to payment.
    Paid Paid orders are orders that have been successfully paid.
    Chargeback Chargeback indicates that the player has issued a complaint regarding the transaction to their credit card or payment provider and that they have been issued a refund. You can either accept or dispute the chargeback.
    Chargeback Reversed Chargeback Reversed indicates that you have successfully disputed a chargeback request and the disputed funds have been returned to you.
    Fulfilled Fulfilled indicates that the order was successful and the player has been granted the item.
    Fulfill Failed Fulfill Failed occurs when the ordered item is no longer available, so the order cannot be fulfilled. If this happens, you’ll need to refund the order.
    Refunding Refunding occurs when our platform has already sent a refund request to the 3rd party payment provider but has not yet received a notification.
    Refunded Refunded indicates that the refund for the order has been successfully processed.
    Refund Failed Refund failed indicates that a technical issue has prevented the refund from being processed.
    Closed Closed indicates that an order has been left unpaid for so long that it’s expired. Unpaid orders expire after 10 minutes.

    orders

  4. The list of the player’s orders appears. Click View to see the order details.

    orders

  5. The Order Details page appears. Here you can see the order summary, details, and history.

    orders

# Get a Player’s Order History

  1. After you get a player’s order, you can view their order history by clicking the View button in the Action column.

  2. In the Order Details panel, click the Order History button.
    orders

  3. The user’s order history appears. You can see when each item was paid for and fulfilled in the Action column.
    orders

# Download an Order Receipt

  1. In the Order Details panel, click the Order Receipt button.
    orders

  2. The download will start immediately. The Order Receipt will be saved as a PDF file.

# Refund an Order

  1. In the Order Details panel, click the Refund button.
    orders

  2. Once the Refund Order form appears, type the Reason why the order is going to be refunded. When you’re done, click the Refund button.

    orders

# Implementing Orders using the SDK

# Create an Order

You can use the following sample code to create an order, by inputting the item ID of the in-game item ordered. The item will be granted automatically to a player as an entitlement.

If you encounter the following error, it means that the player already owns the maximum number of the time that they can. You can verify this using the Check Entitlement function.

ErrorCode.ExceedItemMaxCountPerUser  

# Managing Orders using API

# Query a Player’s Order

  1. Use the Query User Orders - GET /admin/namespaces/{namespace}/users/{userId}/orders endpoint.
  2. Input the Namespace field with the publisher namespace.
  3. Input the User ID.
  4. Select the Status of the order.
  5. Input the Item ID of the item you want to get.

TIP

Status and Item ID are optional. You can leave them empty to display all items with every status.

Upon successful request, the player’s order information will appear. Here is an example of a response to a successful request:

# Get a Player’s Order History

  1. Use the Get User Order Histories - GET /admin/namespaces/{namespace}/users/{userId}/orders/{orderNo}/history endpoint.
  2. Input the Namespace field with the Publisher Namespace.
  3. Input the User ID.
  4. Input the order number in orderNo field.

Upon successful request, the player’s order history will appear. Here is an example of a response to a successful request:

# Download an Order Receipt

  1. Use the Download User Order Receipt - GET /admin/namespaces/{namespace}/users/{userId}/orders/{orderNo}/receipt.pdf endpoint.
  2. Input the Namespace field with the Publisher Namespace.
  3. Input the User ID.
  4. Input the order number in orderNo field.

Upon successful request, the player’s order receipt will appear. A successful request returns Code 200 OK and the downloaded file, which indicates that the request was successful.

# Refund an Order

  1. Use the PUT /admin/namespaces/{namespace}/orders/{orderNo}/refund endpoint.
  2. Input the Namespace field with Publisher Namespace.
  3. Input the order number in orderNo field.
  4. Fill out the Request Body.
    • Input the Description field with the reason why the order is being refunded.

Upon successful request, the refund order will appear. Here is an example of a response to a successful request:

  • Check out Wallets to learn more about how users can store currency to use for orders.
  • Read more about Fulfillment