G2G OpenAPI Beta API Docs

G2G OpenAPI Beta (1.0.0)

Introduction

Get started on the G2G OpenAPI with our guide on managing your information on G2G. The G2G OpenAPI can provide the following functionalities for our sellers:

  • Offer management
  • Inventory management

Authentication

Access keys consist of an access key ID and secret access key.

To access G2G OpenAPI, you will need to request from G2G.

When your request to access G2G OpenAPI is approved, you can create access keys from G2G OpenAPI management page. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.

Authentication is handled via HTTP headers, as shown in the table below:

Param Type Descritpion
g2g-api-key String Your access key ID created in G2G.
Example: c09222e3fc40ffb25fc947f738b1abf1
g2g-userid String Your G2G user ID.
Example: 509205
g2g-signature String Signature generated by API path, api_key, user_id and timestamp via HMAC-SHA256 hashing algorithm.
Example: e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2
g2g-timestamp timestamp This is to indicate the timestamp of the request, in miliseconds. Required for all requests. Expires in 5 minutes.
Example: 1654675838694

Setup API Key

  1. Login to https://www.g2g.com/.

  2. On top right of the menu bar, click on your avatar, select API Integration.

User Bar Menu

  1. Request API integration access if you have not gotten permission to use G2G OpenAPI.

  2. On the API integration page, click "Generate key" to generate the G2G API and Secret key.

API Integration Page

  1. Please copy the secret key and keep it securely. You will not be able to retrieve the secret key if you lose it, only re-generate a new key.

Generate API Key

  1. You can start to send requests to G2G OpenAPI by generating the g2g-signature and adding it to the HTTP request headers.

Verifying Signatures

Javascript 
var CryptoJS = require("crypto-js");

const secretKey = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw"; // Your API Secret Key
const apiKey = "b5769724c1cb1d52c58717d3d12ae2fe"; // Your API Key
const userId = "100000"; // Your User ID
const timestamp = "1653278884000"; // g2g-timestamp
const canonicalUrl = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb"; // API Endpoint 

let canonicalString = canonicalUrl + apiKey + userId + String(timestamp);

const signature = CryptoJS.HmacSHA256(canonicalString, secretKey);

console.log(String(signature)) // This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

Python 
import hashlib, hmac

secret_key = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw" # Your API Secret Key
api_key = "b5769724c1cb1d52c58717d3d12ae2fe" # Your API Key
user_id = "100000" # Your User ID
timestamp = "1653278884000" # g2g-timestamp
canonical_url = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb" # API Endpoint 

canonical_string = canonical_url + api_key + user_id + str(timestamp);

signature = hmac.new(
    key=bytes(secret_key.encode("utf8")),
    msg=bytes(canonical_string.encode("utf8")),
    digestmod=hashlib.sha256,
).hexdigest()

print(signature) # This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

PHP 
$secret_key = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw"; // Your API Secret Key
$api_key = "b5769724c1cb1d52c58717d3d12ae2fe"; // Your API Key
$user_id = "100000"; // Your User ID
$timestamp = "1653278884000"; // g2g-timestamp
$canonical_url = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb"; // API Endpoint 
  
$canonical_string = $canonical_url.$api_key.$user_id.(string)$timestamp;
$signature = hash_hmac("sha256", $canonical_string, $secret_key);
  
echo $signature; // This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

API Call Flows

Create Offer Flow

Create Offer API Call Flow

Upload Code Flow

Upload Code Flow is mainly for Digital Code order.

Create Offer API Call Flow

Order Delivery Flow

Top Up only supported in V2

Order Delivery Flow is mainly for Top Up order.

Deliver Order API Call Flow

Understand delivery attributes for Top Up

  1. Buyer has to fill in Order Information when place order.

Order Information

  1. When you call Get Attributes API, delivery_method_list will be returned in the response.
  2. Under delivery_method_list, lookup attribute_group_list.
  3. From the Order Information sample image, you will get below response:
{
    "attribute_group_list": [
        {
            "attribute_group_id": "e02308e5",
            "attribute_group_name": "User ID",
            "input_field": "text",
            "input_settings": {},
            "is_required": true,
            "attribute_key": "delivery_info_1",
            "attribute_list": []
        },
        {
            "attribute_group_id": "1759fb6c",
            "attribute_group_name": "Servers (Ragnarok X: Next Generation)",
            "input_field": "dropdown",
            "input_settings": {
                "is_searchable": false
            },
            "is_required": true,
            "attribute_key": "delivery_info_2",
            "attribute_list": [
                {
                    "attribute_id": "98f0250f",
                    "attribute_name": "Aldebaran",
                    "sub_attribute_list": []
                },
                {
                    "attribute_id": "6ab853d2",
                    "attribute_name": "Angeling",
                    "sub_attribute_list": []
                },
                ... // more options
            ]
        }
    ]
}
  • The 1st attribute is a text field, which is refers to User ID input and the attribute_key is delivery_info_1.
  • The 2nd attribute is a dropdown field, which is refers to Server input and the attribute_key is delivery_info_2.
  • You are adviced to use attribute_key for integration instead of attribute_group_id or attribute_group_name.
  1. When order is placed, you will receive webhook order.api_delivery and delivery_method_list will be provided in the payload.
{
    "delivery_method_list": [
        {
            "attribute_group_id": "e02308e5",
            "attribute_group_name": "User ID",
            "attribute_key": "delivery_info_1",
            "attribute_id": "",
            "attribute_value": "",
            "value": "hello_world"
        },
        {
            "attribute_group_id": "1759fb6c",
            "attribute_group_name": "Servers (Ragnarok X: Next Generation)",
            "attribute_key": "delivery_info_2",
            "attribute_id": "98f0250f",
            "attribute_value": "Aldebaran",
            "value": ""
        }
    ]
}
  1. From the sample payload above,
  • delivery_info_1 refers to User ID and hello_world is the User ID provided by buyer.
  • delivery_info_2 refers to Servers and Aldebaran is the server chosen by buyer.

Order Status Flow

Order Status Flow

# Order Status Description
1 unpaid Buyer started the checkout process but not yet complete the payment.
2 cancelled Order is cancelled.
3 unpaid (rollback from cancelled) A cancelled order is moved back to unpaid.
4 paid Buyer has completed the checkout process and payment is done and confirmed.
5 start_delivering Delivery is ready.
6 delivering Delivery in progress.
7 awaiting_buyer_confirmation Delivery completed, pending buyer to confirm order received.
8 delivered Buyer has confirmed order received. Quantities in the order is fully delivered.
9 partial_delivered Buyer has confirmed order received. Only some quantities in the order is delivered.
10 delivering (rollback from delivered / partial_delivered) Buyer reported issue after confirmed receipt.
11 refunded Quantity is refunded due to not receiving or defect.

Error Handling

The following code snippet is a sample error response that contains an error code and message pair:

{
  "code": 40400001,
  "message": "The requested resource does not exist.",
  "warning": "",
  "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  "payload": {}
}

When troubleshooting the error, you can divide the error code into two components: REST API HTTP status code and error category code. See the following error code sample:

40400001

  • 404 - HTTP status code 404
  • 00001 - G2G OpenAPI error code

Status Code

The following table summarizes the HTTP response codes you may receive from the G2GOpen API.

Status Code Description
200 Everything worked as expected.
400 The request was unacceptable, often due to missing a required parameter, incorrect data type or incorrect request schema.
401 No valid API key provided. For eg:
  • API key mismatch with user_id
  • The status of the API key is denied
403 The API key doesn't have permissions to perform the request.
404 The requested resource doesn't exist.
409 The request conflicts with another request.
422 Unprocessable Entity.
429 The request cannot be completed because client have exceeded his rate limits.
500 Something went wrong on G2GOpenAPI’s end, these are rare.

Error Code

Code Descritpion
40000001 The request was unacceptable, often due to missing a required parameter.
40100001 The request is not authorized and cannot access the requested resource.
40300001 The application identified with the request is not available.
40400001 The requested resource does not exist.
40900001 The requested resource already exists.
40900002 Data constraint violation.
42200001 Validation error.
42900001 Throttle request.
50000001 The server encounters an unexpected exception while trying to process the request. Please retry the request.

API Versions

Version Descritpion
V1 Deprecated. We encourage to use the latest version of G2G OpenAPI.
V2 Current version of G2G OpenAPI.

G2G Official - OpenAPI Sample

Please visit https://github.com/g2g-official/open-api-sample to download the sample postman collection as a reference to kickstart your API integration.

Product

Everything about your products.

Get Services

Get list of all available services.

query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Brands

Get brands of a service.

path Parameters
service_id
required
string <uuid>
Example: 44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service.

Note: This API have a limit of 1000 results per request
query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

q
string
Example: q=itunes

Search brands by keyword.

after
string <uuid>
Example: after=ba683457-f9d0-4330-bea7-923ed300d2e5

Retrieve next set of brands.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Products

Get products of a brand.

query Parameters
category_id
string <uuid>
Example: category_id=f6fc99db-96d2-4158-a29f-663d9a2f6199

The unique identifier of a category.

service_id
string <uuid>
Example: service_id=44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service. Required when category_id is not provided

brand_id
string <uuid>
Example: brand_id=8c42b2d4-6d2c-4188-931a-240d2f94183f

The unique identifier of a brand. Required when service_id is provided

q
string
Example: q=itunes

Search products by brand keyword.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "5cd2b212-868f-4d0a-b05f-37e93a37529b",
  • "payload": {
    }
}

Get Attributes

Get attributes of a product.

path Parameters
product_id
required
string <uuid>
Example: 4a610301-4e3a-4cc7-b242-35ebc1a521a7

The unique identifier of a product.

Responses

Response samples

Content type
application/json
{
  • "request_id": "e48919cd-12be-4005-ba09-fe4004f08925",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Offer

Everything about your offers.

Create Offer

Create a new offer.

Request Body schema: application/json
product_id
required
string <uuid>

The unique identifier of the product.

title
string

The title of an offer. Not applicable for Giftcard & Top Up

description
string

Description of an offer. Not applicable for Giftcard

min_qty
required
integer >= 1

Minimum purchase quantity.

api_qty
required
int >= 0

The quantity of stock to sell in G2G via OpenAPI.

low_stock_alert_qty
required
int >= 0

When reach low_stock_alert_qty, will receive offer.low_stock webhook

required
Array of objects[ items ]
currency
required
string

Currency ISO code. Reference

unit_price
required
number <double> > 0

Unit price of an offer item.

Array of objects [ 1 .. 3 ] items [ items ]
Array of objects[ items ]

Other currency pricing that you may have for an offer.

Array of objects[ items ]

The wholesale detail setting for other currency that you may have for an offer.

object

Setting to allow or disallowed buyer from specific country to purchase the offer. Default global, no country restriction

delivery_method_ids
Array of strings <uuid>

A list of uid string that respresent delivery method of an offer. Does not required for Gift Card offer

Responses

Request samples

Content type
application/json
{
  • "product_id": "c9bf2323-fa8d-4c88-acc8-87d2ced62b72",
  • "offer_attributes": [
    ],
  • "unit_price": 200.99,
  • "min_qty": 2,
  • "api_qty": 100,
  • "low_stock_alert_qty": 2,
  • "wholesale_details": [
    ],
  • "other_pricing": [
    ],
  • "other_wholesale_details": [
    ],
  • "sales_territory_settings": {
    },
  • "delivery_method_ids": [
    ],
  • "currency": "MYR"
}

Response samples

Content type
application/json
{
  • "request_id": "09b046f7-8fd8-424e-ad95-fa98061acf88",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Get Offer

Get a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Responses

Response samples

Content type
application/json
{
  • "request_id": "793d2a29-42b2-456a-9fdc-788c59c80199",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Update Offer

Update a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Request Body schema: application/json
min_qty
integer >= 1

Minimum purchase quantity.

api_qty
int >= 0

The quantity of stock to sell in G2G via OpenAPI.

low_stock_alert_qty
int >= 0

When reach low_stock_alert_qty, will receive offer.low_stock webhook

Array of objects[ items ]
currency
string

Currency ISO code. Reference

unit_price
number <double> > 0

Unit price of an offer item.

Array of objects [ 1 .. 3 ] items [ items ]
Array of objects[ items ]

Other currency pricing that you may have for an offer.

Array of objects[ items ]

The wholesale detail setting for other currency that you may have for an offer.

object

Setting to allow or disallowed buyer from specific country to purchase the offer. Default global, no country restriction

delivery_method_ids
Array of strings <uuid>

A list of uid string that respresent delivery method of an offer. Does not required for Gift Card offer

Responses

Request samples

Content type
application/json
{
  • "offer_attributes": [
    ],
  • "unit_price": 300.99,
  • "min_qty": 2,
  • "api_qty": 50,
  • "low_stock_alert_qty": 5,
  • "wholesale_details": [
    ],
  • "other_pricing": [
    ],
  • "other_wholesale_details": [
    ],
  • "sales_territory_settings": {
    },
  • "delivery_method_ids": [
    ],
  • "currency": "MYR"
}

Response samples

Content type
application/json
{
  • "request_id": "09b046f7-8fd8-424e-ad95-fa98061acf88",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Delete Offer

Delete a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Responses

Response samples

Content type
application/json
{
  • "request_id": "b186c4e9-fe36-48f5-9545-937b0ab0d72f",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Search Offers

Search for a list of offers.

Request Body schema: application/json
object

The search and filter query settings.

page_size
integer [ 1 .. 100 ]

Specify the number of offers to return per page. Default: 20

page
integer >= 1

Return a result of a page.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "page_size": 1,
  • "page": 1
}

Response samples

Content type
application/json
{
  • "request_id": "ac12caf3-ca5c-45ed-93f4-7ab880855332",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Order

Everything about your orders.

Get Order

Get the summary information of your sold order.

Responses

Response samples

Content type
application/json
{
  • "request_id": "3d12ca6c-0ea3-40c0-8a6e-c689b4d80fa8",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Get Deliveries

Get delivery info based to specific order id.

Note: This API have a limit of 100 results per request. An after key will be return when result is more than the limit
path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

query Parameters
after
string
Example: after=Item#1670568841157TEST-1#D1671691755000

Retrieve next set of result.

Responses

Response samples

Content type
application/json
{
  • "request_id": "a1b452f9-04f5-4892-987a-e71badbe5b99",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Deliver Code

Deliver Codes to specific order when seller received webhook for delivery.

path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

Request Body schema: application/json
delivery_id
required
string

The unique identifier of a delivery operation that was provided in order.api_delivery webhook.

required
Array of objects [ 1 .. 100 ] items [ items ]

Array of codes to be sent to buyer based on specific order_id

Responses

Request samples

Content type
application/json
{
  • "delivery_id": "D1655369534",
  • "codes": [
    ]
}

Response samples

Content type
application/json
{
  • "request_id": "7542860a-d82d-4c59-b41f-ee39ea318552",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Get Delivery Status

Get the status of your delivery operation.

path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

delivery_id
required
string
Example: D1650341633714

The unique identifier of delivery.

Responses

Response samples

Content type
application/json
Example
Delivered
Delivered
Partial Delivered
In Progress
Pending
Unfulfilled
Expired
{
  • "request_id": "f0e7857a-4d11-4115-98dc-d71e387299bc",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Patch Delivery

Update delivered quantity for manual delivery.

path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

delivery_id
required
string
Example: D1650341633714

The unique identifier of delivery.

Request Body schema: application/json
delivered_qty
required
integer

Total quantity of item delivered by seller for this order.

delivery_issue
string
Enum: "incorrect_delivery_detail" "insufficient_stock" "others"

Issue encountered when unable to fulfill the requested deliver quantity.

delivered_at
required
integer

Timestamp in milliseconds when the code is delivered for this delivery.

reference_id
string

A reference identifier for this delivery.

Responses

Request samples

Content type
application/json
{
  • "delivered_qty": 1,
  • "delivery_issue": "others",
  • "delivered_at": 1671693315000,
  • "reference_id": "1670568841157TEST_D1671693034000"
}

Response samples

Content type
application/json
{
  • "request_id": "c6d8a1d9-b710-492d-84c0-cc47544c8453",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Inventory

Everything about your inventories.

Upload Code

Upload code to a specific offer's inventory based on offer id.

Request Body schema: application/json
content
required
string

A digital code for the offer. You can get the code format from Get Offer API.

content_type
required
string
Value: "text/plain"

The content value type.

reference_id
required
string

A reference identifier for the code.

Responses

Request samples

Content type
application/json
{
  • "content": "jKYDpJ3IreMUyCS,05 May 2023",
  • "content_type": "text/plain",
  • "reference_id": "referenceid1"
}

Response samples

Content type
application/json
{
  • "request_id": "7542860a-d82d-4c59-b41f-ee39ea318552",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

View Code Info

View code's info of a specific offer's inventory based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

item_id
required
string <uuid>
Example: 3430aa12-6e5e-4d22-ab75-8af4d44b2914

The unique identifier of an inventory items.

Responses

Response samples

Content type
application/json
{
  • "request_id": "1f01f339-0a53-467b-ba37-35df1ba9c003",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Delete Code

Delete code of a specific offer's inventory based on offer id and inventory_id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

item_id
required
string <uuid>
Example: 3430aa12-6e5e-4d22-ab75-8af4d44b2914

The unique identifier of an inventory items.

Responses

Response samples

Content type
application/json
{
  • "request_id": "cfc5d786-d8f5-4ab6-b485-6c402746412b",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Store

Everything about your store setting

View Store Settings

View seller's Store Settings

Responses

Response samples

Content type
application/json
{
  • "request_id": "f0e7857a-4d11-4115-98dc-d71e387299bc",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Log

Everything about your webhook log

Search Webhook Logs

Search webhook logs.

Request Body schema: application/json
required
object

The search and filter query settings.

limit
integer

Specifies the number of messages to return per page.

sort_order
string
Enum: "asc" "desc"

The ordering of the records.

after
string

Marks the starting point of the search results to retrieve in the result set.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 20,
  • "sort_order": "asc"
}

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "19951185-d16e-4ab5-968d-d1ce66b1b7df",
  • "payload": {
    }
}

Product

Everything about your products.

Get Services

Get list of all available services.

query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Brands

Get brands of a service.

path Parameters
service_id
required
string <uuid>
Example: 44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service.

Note: This API have a limit of 1000 results per request
query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

q
string
Example: q=itunes

Search brands by keyword.

after
string <uuid>
Example: after=ba683457-f9d0-4330-bea7-923ed300d2e5

Retrieve next set of brands.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Products

Get products of a brand.

query Parameters
service_id
required
string <uuid>
Example: service_id=44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service.

brand_id
required
string <uuid>
Example: brand_id=8c42b2d4-6d2c-4188-931a-240d2f94183f

The unique identifier of a brand.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "5cd2b212-868f-4d0a-b05f-37e93a37529b",
  • "payload": {
    }
}

Get Attributes

Get attributes of a product.

path Parameters
product_id
required
string <uuid>
Example: 4a610301-4e3a-4cc7-b242-35ebc1a521a7

The unique identifier of a product.

Responses

Response samples

Content type
application/json
{
  • "request_id": "e48919cd-12be-4005-ba09-fe4004f08925",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Offer

Everything about your offers.

Create Offer

Create a new offer.

Request Body schema: application/json
product_id
required
string <uuid>

The unique identifier of the product.

min_qty
required
integer >= 1

Minimum purchase quantity.

api_qty
required
int >= 0

The quantity of stock to sell in G2G via OpenAPI.

low_stock_alert_qty
required
int >= 0

When reach low_stock_alert_qty, will receive offer.low_stock webhook

required
Array of objects[ items ]
currency
required
string

Currency ISO code. Reference

unit_price
required
number <double> > 0

Unit price of an offer item.

Array of objects [ 1 .. 3 ] items [ items ]
object

Setting to allow or disallowed buyer from specific country to purchase the offer. Default global, no country restriction

Responses

Request samples

Content type
application/json
{
  • "product_id": "c9bf2323-fa8d-4c88-acc8-87d2ced62b72",
  • "offer_attributes": [
    ],
  • "unit_price": 200.99,
  • "min_qty": 2,
  • "api_qty": 100,
  • "low_stock_alert_qty": 2,
  • "wholesale_details": [
    ],
  • "sales_territory_settings": {
    },
  • "currency": "MYR"
}

Response samples

Content type
application/json
{
  • "request_id": "09b046f7-8fd8-424e-ad95-fa98061acf88",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Get Offer

Get a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Responses

Response samples

Content type
application/json
{
  • "request_id": "793d2a29-42b2-456a-9fdc-788c59c80199",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Update Offer

Update a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Request Body schema: application/json
min_qty
integer >= 1

Minimum purchase quantity.

api_qty
int >= 0

The quantity of stock to sell in G2G via OpenAPI.

low_stock_alert_qty
int >= 0

When reach low_stock_alert_qty, will receive offer.low_stock webhook

Array of objects[ items ]
currency
string

Currency ISO code. Reference

unit_price
number <double> > 0

Unit price of an offer item.

Array of objects [ 1 .. 3 ] items [ items ]
object

Setting to allow or disallowed buyer from specific country to purchase the offer. Default global, no country restriction

Responses

Request samples

Content type
application/json
{
  • "offer_attributes": [
    ],
  • "unit_price": 300.99,
  • "min_qty": 2,
  • "api_qty": 50,
  • "low_stock_alert_qty": 5,
  • "wholesale_details": [
    ],
  • "sales_territory_settings": {
    },
  • "currency": "MYR"
}

Response samples

Content type
application/json
{
  • "request_id": "09b046f7-8fd8-424e-ad95-fa98061acf88",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Delete Offer

Delete a specific offer based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

Responses

Response samples

Content type
application/json
{
  • "request_id": "b186c4e9-fe36-48f5-9545-937b0ab0d72f",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Order

Everything about your orders.

Get Order

Get the summary information of your sold order.

Responses

Response samples

Content type
application/json
{
  • "request_id": "3d12ca6c-0ea3-40c0-8a6e-c689b4d80fa8",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Deliver Code

Deliver Codes to specific order when seller received webhook for delivery.

path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

Request Body schema: application/json
delivery_id
required
string

The unique identifier of a delivery operation that was provided in order.api_delivery webhook.

required
Array of objects [ 1 .. 100 ] items [ items ]

Array of codes to be sent to buyer based on specific order_id

Responses

Request samples

Content type
application/json
{
  • "delivery_id": "D1655369534",
  • "codes": [
    ]
}

Response samples

Content type
application/json
{
  • "request_id": "7542860a-d82d-4c59-b41f-ee39ea318552",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Get Delivery Status

Get the status of your delivery operation.

path Parameters
order_id
required
string
Example: 1654240349966TEKP-1

The unique identifier of an order.

delivery_id
required
string
Example: D1650341633714

The unique identifier of delivery.

Responses

Response samples

Content type
application/json
Example
Delivered
Delivered
Partial Delivered
In Progress
Pending
Unfulfilled
Expired
{
  • "request_id": "f0e7857a-4d11-4115-98dc-d71e387299bc",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Inventory

Everything about your inventories.

Upload Code

Upload code to a specific offer's inventory based on offer id.

Request Body schema: application/json
content
required
string

A digital code for the offer. You can get the code format from Get Offer API.

content_type
required
string
Value: "text/plain"

The content value type.

reference_id
required
string

A reference identifier for the code.

Responses

Request samples

Content type
application/json
{
  • "content": "jKYDpJ3IreMUyCS,05 May 2023",
  • "content_type": "text/plain",
  • "reference_id": "referenceid1"
}

Response samples

Content type
application/json
{
  • "request_id": "7542860a-d82d-4c59-b41f-ee39ea318552",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

View Code Info

View code's info of a specific offer's inventory based on offer id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

item_id
required
string <uuid>
Example: 3430aa12-6e5e-4d22-ab75-8af4d44b2914

The unique identifier of an inventory items.

Responses

Response samples

Content type
application/json
{
  • "request_id": "1f01f339-0a53-467b-ba37-35df1ba9c003",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Delete Code

Delete code of a specific offer's inventory based on offer id and inventory_id.

path Parameters
offer_id
required
string
Example: G1650341633714BW

The unique identifier of an offer.

item_id
required
string <uuid>
Example: 3430aa12-6e5e-4d22-ab75-8af4d44b2914

The unique identifier of an inventory items.

Responses

Response samples

Content type
application/json
{
  • "request_id": "cfc5d786-d8f5-4ab6-b485-6c402746412b",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Store

Everything about your store setting

View Store Settings

View seller's Store Settings

Responses

Response samples

Content type
application/json
{
  • "request_id": "f0e7857a-4d11-4115-98dc-d71e387299bc",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Log

Everything about your webhook log

Search Webhook Logs

Search webhook logs.

Request Body schema: application/json
required
object

The search and filter query settings.

limit
integer

Specifies the number of messages to return per page.

sort_order
string
Enum: "asc" "desc"

The ordering of the records.

after
string

Marks the starting point of the search results to retrieve in the result set.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "limit": 20,
  • "sort_order": "asc"
}

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "19951185-d16e-4ab5-968d-d1ce66b1b7df",
  • "payload": {
    }
}

About Webhooks

Use webhooks to get notifications about events in G2G site.

How Webhooks Work

When you register for webhooks in the G2G Developers Center, G2G will send an HTTPS POST request to the configured webhook URL with the relevant data when an event happens.
Please note that:

  • G2G cannot guarantee that you will receive messages immediately or in the right order. If we detects event delivery failure, we will attempt to deliver the event to your application again within 48 hours from the time the event occurred. However, you might not receive messages in the order in which they occurred.
  • Please make sure your application can handle receiving the same event more than once.

When you receive a webhook, you must:

  • Verify its signature to make sure that it was sent by G2G.
  • Respond with a HTTP 200 status, else G2G will attempt to resend the message to you.

Setup Webhooks

  1. Login to https://www.g2g.com/.

  2. On top right of the menu bar, click on your avatar, select API Integration.

User Bar Menu

  1. Under the Webhook section on the API integration page,

User Bar Menu

Settings Description
Developer contact G2G will send an alert email to this contact when your system does not respond upon receiving the webhook message.
Callback URL G2G will send the webhook message to this URL. The secret token is mandatory. G2G will use it to create a hash signature that is passed along in the g2g-signature. You can generate secret token on your own or use the "Generate random secret token" provided by G2G. Please copy the secret key and keep it securely.
Events You must fill in the callback URL before configuring webhook events. G2G will send webhook message to your system for the events you selected. By selecting all events, all existing events and any future incoming events will also be selected.

Webhook Resend Policy

If your application does not respond with 200 status code, G2G will try to send the message to you again up to 5 additional attempt, by following the retry schedule:

Retry Attempt Next Resend Interval (minute)
1 30
2 60
3 120
4 240
5 480

Message Signature

Event Header

Whenever webhook was triggered by an event, a signature will be embeded in the header.

Header Type Description
g2g-signature String Signature generated by webhook URL, api_key, user_id and timestamp via HMAC-SHA256 hashing algorithm.
Example: e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2
g2g-timestamp String The timestamp in milliseconds when G2G send the message to you.
Example: 1654576148000

Verifying Signature

Python 
import hashlib, hmac

webhook_secret_token = "gBW1wXgBNnA" # Your Webhook Secret Token
user_id = "100000" # Your User ID
timestamp = "1653278884000" # g2g-timestamp
webhook_url = "https://www.your_webhook_url.com"

canonical_string = webhook_url + user_id + str(timestamp);

signature = hmac.new(
    key=bytes(webhook_secret_token.encode("utf8")),
    msg=bytes(canonical_string.encode("utf8")),
    digestmod=hashlib.sha256,
).hexdigest()

print(signature) # This value should match with g2g-signature, which is 645343db00f974f5dab1f9e9ed8d4846a265e150291009fe40bfbdf437cfa16a

Events

Orders

The webhooks for different stage of orders

Event Trigger
order.created Buyer placed the order but not yet paid.
order.confirmed Buyer has made the payment and payment is confirmed.
order.delivery_status The result of your delivery request, it could be fully delivered / partial delivered / unfulfilled
Note: If you are not subscribed to this event, you can use Get Delivery Status API to check your delivery status.
order.api_delivery Seller is ready to deliver codes via API.
Note: Seller should start prepare deliver the codes when receive this event. Please refer to Deliver Code API to deliver codes
order.cancelled The payment of the order is unsuccessful and cancelled.
order.completed Buyer has confirmed order received.
order.rollback_cancelled A cancelled order is moved back to unpaid.
order.rollback_completed Buyer reported issue after confirmed receipt.
order.case_opened Buyer reported an issue of the order.
Note: Seller should investigate the reported case from G2G resolution center when receive this event.

Offers

The webhooks for offer

Event Trigger
offer.low_stock Seller's offer is below the low stock threshold.

order.created Webhook

The webhook is triggered when buyer placed the order but not yet paid.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.created"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.created",
  • "payload": {
    }
}

order.confirmed Webhook

The webhook is triggered when buyer has made the payment and payment is confirmed.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.confirmed"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.confirmed",
  • "payload": {
    }
}

order.delivery_status Webhook

The webhook is triggered when order item is delivered.

Note: If you are not subscribed to this event, you can use Get Delivery Status API to check your delivery status.
header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.delivery_status"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
Example
Delivered
Delivered
Partial Delivered
Unfulfilled
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1661162265411,
  • "event_type": "order.delivery_status",
  • "payload": {
    }
}

order.api_delivery Webhook

The webhook is triggered to notify seller to start deliver via API.

Note: Seller should start prepare deliver the codes when receive this event. Please refer to Deliver Code API to deliver codes
header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.api_delivery"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
Example
Top Up
Top Up
Gift Card
{
  • "id": "45252cb8-5f79-4b31-a0d8-761760bd3e57-1",
  • "event_happened_at": 1671693034000,
  • "event_type": "order.api_delivery",
  • "payload": {
    }
}

order.cancelled Webhook

The webhook is triggered when the payment of the order is unsuccessful and cancelled.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.cancelled"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.cancelled",
  • "payload": {
    }
}

order.refunded Webhook

The webhook is triggered when order was refunded.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.refunded"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "a8d99337-ea80-40c8-8b75-6c4cc191668a-1",
  • "event_happened_at": 1666017142604,
  • "event_type": "order.refunded",
  • "payload": {
    }
}

order.completed Webhook

The webhook is triggered when an order is completed.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.completed"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.completed",
  • "payload": {
    }
}

order.rollback_cancelled Webhook

The webhook is triggered when a cancelled order is moved back to unpaid order.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.rollback_cancelled"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.rollback_cancelled",
  • "payload": {
    }
}

order.rollback_completed Webhook

The webhook is triggered when a completed order is rollback to delivering.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.rollback_completed"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.rollback_completed",
  • "payload": {
    }
}

order.case_opened Webhook

The webhook is triggered when buyer reported an issue of the order.

Note: Seller should investigate the reported case from G2G resolution center when receive this event.
header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "order.case_opened"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1652090542890,
  • "event_type": "order.case_opened",
  • "payload": {
    }
}

offer.low_stock Webhook

The webhook is triggered when seller's offer is below the low stock threshold.

header Parameters
g2g-signature
string

The signed signature for webhook payload verification

g2g-timestamp
string

The timestamp when post the webhook

Request Body schema: application/json
id
string

The event ID of the request.

event_happened_at
integer

Timestamp in milliseconds when the event occured.

event_type
string
Value: "offer.low_stock"

The type of the webhook event.

object

Request payload.

Responses

Request samples

Content type
application/json
{
  • "id": "341a6ae1-34da-486e-b984-91a6f44cea07",
  • "event_happened_at": 1654240354288,
  • "event_type": "offer.low_stock",
  • "payload": {
    }
}

V2 Breaking Changes

  • Product

    • Get products by categories.
      • In OpenAPI V2, obtaining product information has become easier by providing the category ID obtained from the Get Service API.
    • Introduce Top Up products and its delivery methods.
      • The Get Attributes V2 API will now show the available delivery methods for Top Up products.

  • Offer

    • Support multiple currencies for Create & Update Offer.
      • Unit prices in different currencies are supported by adding other_pricing.
      • Wholesale prices in different currencies can be added in other_wholesale_details.

  • Order

    • Support retrieving multiple delivery information based on an order.
    • Introduce a new API to update delivery status of Top Up orders.
      • The Patch Delivery API allows users to inform the G2G system that the requested item has been delivered to the buyer.

Migrate To V2

The required action of the migration consists in:

  • Updating all request URIs to use the V2 URI endpoint.
  • Update the parameters and request bodies.
  • Update the response parsing.
Get Service V1 API
https://open-api.g2g.com/v1/services
Response
{
    "code": 20000001,
    "message": "",
    "warning": "",
    "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
    "payload": {
        "service_list": [
            {
                "service_id": "44b3148a-0dc8-4262-81d8-c762559f0d74",
                "service_name": "Gift Cards",
                "delivery_method": "instant_code_delivery"
            }
        ]
    }
}
Get Service V2 API
https://open-api.g2g.com/v2/services
Response
{
    "code": 20000001,
    "message": "",
    "warning": "",
    "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
    "payload": {
        "service_list": [
            {
                "service_id": "44b3148a-0dc8-4262-81d8-c762559f0d74",
                "service_name": "Gift Cards",
                "categories": [
                    {
                        "category_name": "Gift Cards",
                        "category_id": "f6fc99db-96d2-4158-a29f-663d9a2f6199"
                    },
                    {
                        "category_name": "Video Games",
                        "sub_categories": [
                            {
                                "category_name": "PC Platform",
                                "category_id": "2994a61d-3993-44ba-8190-e3daac599278"
                            },
                            {
                                "category_name": "PSN (Playstation) Platform",
                                "category_id": "96364cef-838f-49c0-9efb-0fa90dfa06d2"
                            },
                            {
                                "category_name": "Xbox Platform",
                                "category_id": "148255f6-4ab4-4af4-833d-4deedb4fd574"
                            },
                            {
                                "category_name": "Nintendo Switch Platform",
                                "category_id": "dc67a04b-3aa1-460c-aaa3-549ebecb3404"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Changelog

March 2023

2023-03-13

Feature

  • Introduce G2G OpenApi V2. please refer to V2 Breaking Changes
  • Improved order.created webhook to support other_pricing info

December 2022

2022-12-21

Fixes

  • Improved Get Brands api to support retrieve the next set of results with after parameter.
  • Set Get Brands api results per request to 1000

November 2022

2022-11-10

Feature

  • Added order.refunded event webhook that will be send to seller each time seller's order being refunded. To ensure deliverability please make sure order.refunded webhook is selected in API Integration

September 2022

2022-09-06

Fixes

  • Improved Update Offer api all request body parameter become optional
  • Improved Update Offer api to required to pass in at least one parameter in request body
  • Improved order.api_delivery webhook to include expired_at value in delivery summary section

2022-09-01

Feature

  • Introduce new G2G OpenAPI in beta