IAP Publish API

The IAP Publish API is used to view, register, modify, and remove Samsung In-App Purchase (IAP) items.

Note :

Using the IAP Publish API to register, modify, or delete an item immediately changes it within the content, even when the content is in the For Sale state.

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.

Requirements

In order to use the IAP Publish API, the following is required:

The IAP Publish API is part of the Galaxy Store Developer API. You must meet all of the requirements of the Galaxy Store Developer API including, but not limited to, creating the access token, including the access token in the authorization header of every IAP Publish API call, and having commercial seller status to manage in-app purchase items.
The IAP Publish API must be connected with the content in the In App Purchase tab area of Seller Portal. To create this connection, you must either initially distribute your content using the Content Publish API or the content must be in the For Sale state in Seller Portal. If this connection does not exist, matching product information cannot be retrieved.
You must integrate IAP Helper into your app. All binaries registered in your content must support IAP.

If these requirements are not met, error code 106 is returned.

Authorization parameters

Every request must include authorization header parameters which specify the content type, your access token, and service account ID and the URL path must contain the package name. See Create an Access Token for more information about how to create an access token and service account ID.

Attribute	In	Description
Authorization	header	Required .Use `Bearer <your-access-token>` where <your-access-token> is the access token you requested from the Galaxy Store authentication server
service-account-id	header	Required. The service account ID used to create the JWT associated with the access token (can be found in the Assistance > API Service area of Seller Portal)
content-type	header	Required. Must be `application/json`
packageName	path	Required. The app's package name

The following example shows the header used with the IAP Publish APIs:

curl -X IAP_PUBLISH_API_REQUEST \
  -H  "content-type: application/json" \
  -H  "Authorization: Bearer <your-access-token>" \
  -H  "service-account-id: <your-service-account-id>"

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

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	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.

Tip :

To modify an app, use the response from View individual item to create the input required for this request.

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 : Local price 0.69 is lower than minimal price 0.99 `118`: Price is lower than minimum unit : Local price 1.099 is not matched minimal price unit 0.01 `400`: BadRequest with wrong in app product info
401 Unauthorized	`101`: User doesn't have permission to change this app `103`: Fail 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 ItemId with the requested packageName