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