---
title: >-
  Session creation payloads now include ISO 3166-2 province codes - Shopify
  developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/payment-session-payloads-now-include-iso-3166-2-province-codes
  md: >-
    https://shopify.dev/changelog/payment-session-payloads-now-include-iso-3166-2-province-codes.md
metadata:
  effectiveApiVersion: 2025-07
  affectedApi:
    - displayName: Payments Apps API
      handle: payments-apps-api
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2025-03-27T11:03:09-04:00'
  postedAt: '2025-04-14T12:00:00-04:00'
  updatedAt: '2025-04-08T14:08:54-04:00'
  effectiveAt: '2025-04-01T12:00:00-04:00'
---

April 14, 2025

Tags:

* Payments Apps API
* 2025-07

# Session creation payloads now include ISO 3166-2 province codes

As of the [Payments Apps API](https://shopify.dev/docs/api/payments-apps) version 2025-07, session creation payloads now include a new field for standardized province codes. For example, `ON` represents Ontario, and `QC` represents Québec. The `province` field, which contains the name of the province as a string, remains in the payload. This addition ensures more reliable handling of provinces by eliminating translation inconsistencies and guaranteeing accurate regional identification.

The updated payload structure is as follows:

```diff
{
  "province": "Québec",
+ "province_code": "QC",
  "country_code": "CA"
}
```

The province code adheres to the ISO 3166-2 standard and is available in API version 2025-07 and later. Existing payment apps that rely solely on province names will continue to function without any changes. For detailed implementation guidance, please refer to our [payment processing documentation](https://shopify.dev/docs/apps/build/payments/request-reference).