en zh

Samsung IAP Publish API

The Samsung IAP Publish API is used to view, register, modify, and remove Samsung In-App Purchase (IAP) items. Before you can start using the IAP Publish API, you must meet all requirements and use the required authorization header parameters in your requests. See Get Started with the IAP APIs for more information.

The following is a quick reference to the IAP Publish APIs:

Name Request Description
View item list

GET /iap/v6/applications/:packageName/items Request a list of item information within a scope appropriate for the page and size.
View individual item

GET /iap/v6/applications/:packageName/items/:id Request detailed information on one item.
Create item

POST /iap/v6/applications/:packageName/items Register an in-app item.
Modify item

PUT /iap/v6/applications/:packageName/items Modify an in-app item.
Partial item modification

PATCH /iap/v6/applications/:packageName/items Modify the specified parameters of an in-app item.
Remove item

DELETE /iap/v6/applications/:packageName/items/:id Remove an in-app item.

See In-App Purchase for more information about IAP functionality in Seller Portal.

View item list

Request a list of item information within a scope appropriate for the page and size.

Request

GET /iap/v6/applications/:packageName/items?page={}&size={}
Name Type In Description
page int query Required. Number of pages of content to return

size int query Required. Number of items to be returned on a page

curl \
  -X GET \
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items?page=1&size=20"

Response

Parameters

Name Type Description
id string Unique identifier of the in-app item registered in Seller Portal.
title string Title of the in-app item registered in Seller Portal.
description string Brief explanation of the in-app item registered in Seller Portal.
type string In-App item type.

  • CONSUMABLE: An item that can be purchased one or more times and remains effective or available in the app until it is used one time (for example, coins, special powers, or gems).
  • NON_CONSUMABLE: An item that is purchased only once and remains effective or available in the app at all times, even after deletion and re‑installation of the app (for example, game boards or an upgrade).
  • UNSPECIFIED: An unknown item type.

status string Item distribution status in Seller Portal.

  • PUBLISHED: Item is for sale in Galaxy Store.
  • UNPUBLISHED: Item is not available in Galaxy Store.
  • REMOVED: Item has been removed from Galaxy Store.
  • UNSPECIFIED: Item status is not known.

itemPaymentMethod.phoneBillStatus Boolean Whether or not the item is paid with an automatic payment on a phone bill.

  • true: The item is paid by an automatic payment on a phone bill.
  • false: The item is not paid by an automatic payment on a phone bill.

usdPrice number The base price in USD (United States of America dollars) of the item. The price can be set between 0 and 400.
prices[].countryId string Three-character country code (ISO 3166) of the country where the item is sold.

prices[].currency string Three-character currency code (ISO 4217) of the specified country's currency (for example, EUR, GBP, USD).

prices[].localPrice string Price of the item in the specified country's currency.
totalCount number Number of items listed in the response.

Success

Status: 200 Success
{
  "itemList": [
    {
      "id": "one_gallon_gas",
      "title": "1 Gallon gas",
      "description": "Fuel for driving game",
      "type": "CONSUMABLE",
      "status": "PUBLISHED",
      "itemPaymentMethod": {
        "phoneBillStatus": true
      },
      "usdPrice": 0.900,
      "prices": [
        {
          "countryId": "KOR",
          "currency": "KRW",
          "localPrice": "1000.000"
        },
        {
          "countryId": "USA",
          "currency": "USD",
          "localPrice": "0.900"
        }, ...
      ]
    }, ...
  ],
  "totalCount": 3
}

See Failure response codes for a list of possible response codes when a request fails.

View individual item

Request detailed information about one item.

Request

GET /iap/v6/applications/:packageName/items/:id
Name Type Description
id string Required. Unique identifier of the in-app item registered in Seller Portal.

curl \
  -X GET
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items/one_gallon_gas"

Response

See View item response parameters for a description of the response parameters.

Success

Status: 200 Success
{
  "id": "one_gallon_gas",
  "title": "1 Gallon gas",
  "description": "Fuel for driving game",
  "type": "CONSUMABLE",
  "status": "PUBLISHED",
  "itemPaymentMethod": {
    "phoneBillStatus": true
  },
  "usdPrice": 0.900,
  "prices": [
   {
      "countryId": "KOR",
      "currency": "KRW",
      "localPrice": "1000.000"
    },
    {
      "countryId": "USA",
      "currency": "USD",
      "localPrice": "0.900"
    }, ...
  ]
}

See Failure response codes for a list of possible response codes when a request fails.

Create item

Register an in-app item.

Request

POST /iap/v6/applications/com.package.name/items
Name Type Description
id string Required. Unique identifier of the in-app item registered in Seller Portal.

title string Required. Title of the in-app item registered in Seller Portal.

description string Required. Brief explanation of the in-app item registered in Seller Portal.

type string Required. In-App item type.

  • CONSUMABLE: An item that can be purchased one or more times and remains effective or available in the app until it is used one time (for example, coins, special powers, or gems).
  • NON_CONSUMABLE: An item that is purchased only once and remains effective or available in the app at all times, even after deletion and re‑installation of the app (for example, game boards or an upgrade).
  • UNSPECIFIED: An unknown item type.

status string Required. Item distribution status in Seller Portal.

  • PUBLISHED: Item is for sale in Galaxy Store.
  • UNPUBLISHED: Item is not available in Galaxy Store.
  • REMOVED: Item has been removed from Galaxy Store.
  • UNSPECIFIED: Item status is not known.

itemPaymentMethod.phoneBillStatus Boolean Required. Whether or not the item is paid with an automatic payment on a phone bill.

  • true: The item is paid by an automatic payment on a phone bill.
  • false: The item is not paid by an automatic payment on a phone bill.

usdPrice number Required. The base price in USD (United States of America dollars) of the item. The price can be set between 0 and 400.

prices[].countryId string Required. Three-character country code (ISO 3166) of the country where the item is sold.

prices[].currency string Three-character currency code (ISO 4217) of the specified country's currency (for example, EUR, GBP, USD).

prices[].localPrice string Required. Price of the item in the specified country's currency.

curl \
  -X POST \
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  -d '{"id":"one_gallon_gas","title":"1 Gallon gas","description":"Fuel for driving game","type":"CONSUMABLE","status":"PUBLISHED","itemPaymentMethod":{"phoneBillStatus":true},"usdPrice":0.99,"prices":[{"countryId":"KOR","currency":"KRW","localPrice":"1000"},{"countryId":"USA","currency":"USD","localPrice":"0.99"}]}' \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items"

Response

Success

Status: 200 Success
{
  "id": "one_gallon_gas",
  "type": "CONSUMABLE",
  "status": "PUBLISHED",
  "prices": [
    {
      "countryId": "KOR",
      "currency": "KRW",
      "localPrice": "1000.000"
    },
    {
      "countryId": "USA",
      "currency": "USD",
      "localPrice": "0.99"
    }, ...
  ]
}

See Failure response codes for a list of possible response codes when a request fails.

Modify item

Modify an in-app item. The request replaces all existing information, except the content ID, of the item.

Request

PUT /iap/v6/applications/:packageName/items

See Create item request for a description of the request parameters.

curl \
  -X PUT \
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  -d '{"id":"one_gallon_gas","title":"1 Gallon gas","description":"Fuel for driving game fix","type":"CONSUMABLE","status":"PUBLISHED","itemPaymentMethod":{"phoneBillStatus":true},"usdPrice":1,"prices":[{"countryId":"KOR","currency":"KRW","localPrice":"1000"},{"countryId":"USA","currency":"USD","localPrice":"1"}]}' \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items"

Response

Success

Status: 200 Success
{
  "id": "one_gallon_gas",
  "type": "CONSUMABLE",
  "status": "PUBLISHED",
  "prices": [
    {
      "countryId": "KOR",
      "currency": "KRW",
      "localPrice": "1000.000"
    },
    {
      "countryId": "USA",
      "currency": "USD",
      "localPrice": "1"
    }, ...
  ]
}

See Failure response codes for a list of possible response codes when a request fails.

Partial item modification

Modify the title, countryId, or localPrice of an in-app item. The id cannot be modified. Parameters that are not specified are not modified.

Request

PATCH /iap/v6/applications/:packageName/items
Name Type Description
id string Required. Unique identifier of the in-app item registered in Seller Portal.

title string Title of the in-app item registered in Seller Portal.
prices[].countryId string Three-character country code (ISO 3166) of the country where the item is sold.

prices[].localPrice string Price of the item in the specified country's currency.
curl \
  -X PATCH \
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  -d '{"id":"one_gallon_gas","title":"2 Gallon gas"}' \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items"

Response

Success

Status: 200 Success
{
  "id": "one_gallon_gas",
  "type": "CONSUMABLE",
  "status": "PUBLISHED"
}

See Failure response codes for a list of possible response codes when a request fails.

Remove item

Remove an in-app item.

Request

DELETE /iap/v6/applications/:packageName/items/:id
Name Type In Description
id string path Required. Unique identifier of the in-app item registered in Seller Portal.

curl \
  -X DELETE
  -H "content-type:application/json" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "service-account-id: <your-service-account-id>" \
  "https://devapi.samsungapps.com/iap/v6/applications/com.package.name/items/one_gallon_gas"

Response

Success

Status: 200 OK
{
  "id": "one_gallon_gas"
}

See Failure response codes for a list of possible response codes when a request fails.

Failure response codes

The following are response codes you may see when the request fails.

Status Code and message
400
Bad Request

  • 109: Subscription is not yet supported
  • 117: Price is under minimum value. For example, the local price of 0.69 is lower than the minimum price of 0.99.
  • 118: Price is lower than minimum unit. For example, the local price of 1.099 does not match the minimal price unit of 0.01
  • 400: Bad request with wrong in-app product information
401
Unauthorized

  • 101: User doesn't have permission to change this app
  • 103: Failed to verify gateway server authorization
404
Not Found

  • 104: Content doesn't exist. Please create content first.
  • 106: ItemGroup doesn't exist in production level. Need to publish IAP-supported app.
  • 110: Item does not exist
409
Conflict

  • 105: The item already exists with the requested id
  • 107: There are multiple ItemGroupIds or ItemIds with the requested packageName