Samsung IAP Subscription API

The Samsung IAP Subscription API is used to cancel, refund, revoke, and check the status of Samsung In-App Purchase (IAP) subscription items. Before you can start using the IAP Subscription API, you must meet all requirements, use the required authorization header parameters, and use the required URL path paremeters in your requests. See Get Started with the IAP APIs for more information.

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

Name

Method

Description

Cancel subscription

PATCH

Cancel the subscription corresponding to the given purchaseId.

When a subscription is canceled, automatic payments are no longer made after the current subscription period ends. Customers can use the subscription item until the end of the current subscription period.

Refund subscription

PATCH

Reimburse the most recent payment for the subscription corresponding to the given purchaseId.

The current subscription continues.

Revoke subscription

PATCH

Immediately cancel the subscription and reimburse the most recent payment for the subscription corresponding to the given purchaseId.

When a subscription is revoked, customers instantly lose the ability to use the subscription item, even if the current subscription period has not ended. And, automatic payments are no longer made after the current subscription period ends.

Check status of subscription

GET

Check the subscription status.


Cancel, refund, or revoke subscription

Cancel, refund, or revoke a subscription. See the table below for a description of each action.

Request

PATCH /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId>

Body parameter

Name

Type

Description

action

string

Required. The task to perform. Must be one of the following:
  • cancel: End the subscription. When a subscription is cancelled, the customer can still access the item until the end of the current subscription period. After the current subscription period ends, access to the item should be blocked.
  • refund: Reimburse the most recent payment to the subscriber. The subscriber can still use the subscription item. Use this if there is a service error or you want to issue a complimentary coupon.
  • revoke: Immediately cancel the subscription and immediately refund the most recent payment. When a subscription is cancelled, the customer instantly loses the ability to use the subscription item, even if the current subscription period has not ended. Access to the item should be blocked immediately.

curl -i -X PATCH \
  -H  "Content-Type: application/json" \
  -H  "Authorization: Bearer <your-access-token>" \
  -H  "service-account-id: <your-service-account-id>" \
  -d '{"action" : "cancel | refund | revoke"}' \
'https://devapi.samsungapps.com/iap/seller/v6/applications/<packageName>/items/purchases/subscriptions/<purchaseId>'

Response

Name

Type

Description

code

string

Success code, IAP internal error code, or HTTP status code

message

string

Detailed information about error or HTTP reason

{
   "code" : "0000",
   "message" : "Success"
}

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

Check status of subscription

Get the subscription status, including item information and purchase information, which can be used to verify the purchase of an item.

Request

GET /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId>
curl -i -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/seller/v6/applications/<packageName>/items/purchases/subscriptions/<purchaseId>'

Response

Parameters

Parameter

Type

Description

subscriptionPurchaseDate

String

Date and time of the item's initial purchase and payment transaction
(YYYY-MM-DD HH:mm:ss GMT)

subscriptionEndDate

String

Date and time when the subscription expires
(YYYY-MM-DD HH:mm:ss GMT)

subscriptionStatus

String

Current status of the item subscription
"ACTIVE" The subscription is current and in effect.
"CANCEL" The user canceled the subscription. Check the subscriptionEndDate to see if the subscription period has ended (as the canceled item is still valid until the current suscription period has ended).

subscriptionFirstPurchaseID

String

Unique identifier of the initial purchase of the item

countryCode

String

Country code (3 alphabetic characters) of the purchaser's location (for example, KOR, USA)

price[].localCurrencyCode

String

Currency code (3 alphabetic characters) of the purchaser's local currency paid for the item (for example, EUR, GBP, USD)

price[].localPrice

double

Cost (in the user's local currency) that the user paid for the in-app item

price[].supplyPrice

double

Total amount of the item price plus the applied tax

itemID

String

Unique identifier of the in-app item registered in Seller Portal

freeTrial

String

Whether or not the in-app item's subscription is currently in a free trial period:
"Y" Free trial period
"T"Tiered (lower/introductory) price period
"N" Regular price period

realMode

String

For regular purchases, whether the actual payment was made when the user purchased the item.
"Y" Samsung IAP was set to production mode. The actual payment was made.
"N" Samsung IAP was set to Test Mode. The actual payment was NOT made.

latestOrderId

String

Identifier (19 alphanumeric characters) of the most recent payment. it can be an initial payment or a renewal payment.
Order IDs are displayed in the user's renewal receipt.

totalNumberOfTieredPayment

String

Total number of tiered price payments

currentPaymentPlan

String

Current period the subscription is in:
"F" : Free trial period
"R" : Regular price period
"T" : Tiered (lower) price period

totalNumberOfRenewalPayment

String

Total number of payments made for initial and renewal subscriptions

cancelSubscriptionDate

String

Date and time the subscription was stopped
(YYYY-MM-DD HH:mm:ss GMT)

cancelSubscriptionReason

String

Cause of the subscription stoppage:
"1" User canceled the subscripton.
"2" System canceled the subscription
(for example, renewal test was finished).
"3" Billing error (for example, user payment information was no longer valid).
"4" Item is not available for purchase at the time of renewal.
"5" Unknown errors

gracePeriodYN

String

Whether or not the in-app item's subscription is currently in a grace period:
"Y" The subscription is in a grace period
"N" The subscription is not in a grace period

gracePeriodEndDate

String

The end date and time of the grace period (YYYY-MM-DD HH:mm:ss GMT)
If the subscription is not in a grace period (gracePeriodYN = "N"), this value is set to NULL.

priceChange[].priceChangeMode

String

The mode of the price change:
"1" Price increase which requires the user’s consent
"2" Price increase which does not require the user’s consent
"3" Price decrease, which does not require the user’s consent

priceChange[].priceChangeStatus

String

The status of the price change:
"WAITING" Waiting for the subscriber to answer
"CONFIRMED" The price change is acknowledged by the subscriber (either the subscriber consented or did not consent to the increase in price)
"APPLIED" The subscriber is charged the new price

priceChange[].priceChangeConsentDate

String

Date and time the subscriber consented
(YYYY-MM-DD HH:mm:ss GMT)

priceChange[].expectedNewPriceChargeDate

String

Date and time the new price will affect the subscriber
(YYYY-MM-DD HH:mm:ss GMT)

priceChange[].newPrice[].localCurrencyCode

String

Local currency code (3 alphabetic characters) of the changed price (for example, EUR, GBP, USD)

priceChange[].newPrice[].localPrice

double

Cost (in the user's local currency) that the user paid for the in-app item

Success

{
   "subscriptionPurchaseDate": "2024-05-31 01:30:13 GMT",
   "subscriptionEndDate": "2024-06-03 01:03:30 GMT",
   "subscriptionStatus": "CANCEL",
   "subscriptionFirstPurchaseID": "649922f760188d759c19636c4efe130d0743bd6f5446504e0a8e68b0010e0ab7",
   "countryCode": "KOR",
   "price": {
      "localCurrencyCode": "KRW",
      "localPrice": 1000.0,
      "supplyPrice": 1000.0
   },
   "itemID": "subsc_30MIN",
   "freeTrial": "N",
   "realMode": "Y",
   "latestOrderId": "S20240531KR01924958",
   "totalNumberOfTieredPayment": "0",
   "currentPaymentPlan": "R",
   "totalNumberOfRenewalPayment": "3",
   "cancelSubscriptionDate": "2024-06-03 01:03:29 GMT",
   "cancelSubscriptionReason": "2",
   "gracePeriodYN": "Y",
   "gracePeriodEndDate": "2024-06-10 01:03:29 GMT",
   "priceChange": {
      "priceChangeMode": "1",
      "priceChangeStatus": "WAITING",
      "priceChangeConsentDate": null,
      "expectedNewPriceChargeDate": "2024-05-31 02:22:02 GMT",
      "newPrice": {
         "localCurrencyCode": "KRW",
         "localPrice": 1500.0
      }
   }
}

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

Failure response codes

Status

Code and message

400
Bad Request

  • SLR_4001: Seller does not match
  • SLR_4014: Item does not exist
  • SLR_4015: Missing required parameter
  • SLR_4016: Purchase ID does not exist
  • SLR_4017: Unknown action parameter
  • SLR_4018: The purchase ID cannot be refunded
401
Unauthorized

  • SLR_4008: Failed to verify gateway server authorization
404
Not Found

  • SLR_4006: Application ID does not exist
406
Not Acceptable

  • SLR_4019: The purchase ID has already been suspended and will not be renewed
  • SLR_4020: The purchase ID has already been refunded
  • SLR_4021: Failed to cancel the subscription for an unknown reason
  • SLR_4022: Failed to refund the subscription for an unknown reason
  • SLR_4023: Failed to revoke the subscription for an unknown reason