en zh

Samsung IAP Publish API

The Samsung IAP Publish API is used to view, register, modify, and remove Samsung In-App Purchase (IAP) products. 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 product list	GET /iap/v6/applications/:packageName/items	Request a list of product information within a scope appropriate for the page and size.
View individual product	GET /iap/v6/applications/:packageName/items/:id	Request detailed information on one product.
Create product	POST /iap/v6/applications/:packageName/items	Register an in-app product.
Modify product	PUT /iap/v6/applications/:packageName/items	Modify an in-app product.
Partial product modification	PATCH /iap/v6/applications/:packageName/items	Modify the specified parameters of an in-app product.
Remove product	DELETE /iap/v6/applications/:packageName/items/:id	Remove an in-app product.

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

View product list

Request a list of product 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 products 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 product registered in Seller Portal.
title	string	Title of the in-app product registered in Seller Portal.
description	string	Brief explanation of the in-app product registered in Seller Portal.
type	string	In-App product 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 product type.
status	string	Product distribution status in Seller Portal. PUBLISHED: Product is for sale in Galaxy Store. UNPUBLISHED: Product is not available in Galaxy Store. REMOVED: Product has been removed from Galaxy Store. UNSPECIFIED: Product status is not known.
itemPaymentMethod.phoneBillStatus	Boolean	Whether or not the product is paid with an automatic payment on a phone bill. true: The product is paid by an automatic payment on a phone bill. false: The product 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 product. The price can be set between 0 and 400.
prices[].countryId	string	Three-character country code (ISO 3166) of the country where the product 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 product in the specified country's currency.
totalCount	number	Number of products 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 product

Request detailed information about one product.

Request

GET /iap/v6/applications/:packageName/items/:id

Name	Type	Description
id	string	Required. Unique identifier of the in-app product 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 product 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 product

Register an in-app product.

Request

POST /iap/v6/applications/com.package.name/items

Name	Type	Description
id	string	Required. Unique identifier of the in-app product registered in Seller Portal.
title	string	Required. Title of the in-app product registered in Seller Portal.
description	string	Required. Brief explanation of the in-app product registered in Seller Portal.
type	string	Required. In-App product 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 product type.
status	string	Required. Product distribution status in Seller Portal. PUBLISHED: Product is for sale in Galaxy Store. UNPUBLISHED: Product is not available in Galaxy Store. REMOVED: Product has been removed from Galaxy Store. UNSPECIFIED: Product status is not known.
itemPaymentMethod.phoneBillStatus	Boolean	Required. Whether or not the product is paid with an automatic payment on a phone bill. true: The product is paid by an automatic payment on a phone bill. false: The product 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 product. The price can be set between 0 and 400.
prices[].countryId	string	Required. Three-character country code (ISO 3166) of the country where the product 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 product 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 product

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

Request

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

See Create product 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 product modification

Modify the title, countryId, or localPrice of an in-app product. 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 product registered in Seller Portal.
title	string	Title of the in-app product registered in Seller Portal.
prices[].countryId	string	Three-character country code (ISO 3166) of the country where the product is sold.
prices[].localPrice	string	Price of the product 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 product

Remove an in-app product.

Request

DELETE /iap/v6/applications/:packageName/items/:id

Name	Type	In	Description
id	string	path	Required. Unique identifier of the in-app product 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: Product does not exist
409 Conflict	105: The product already exists with the requested id 107: There are multiple ItemGroupIds or ItemIds with the requested packageName