Skip to main content

Practical guidelines

Working with APIs can be challenging. In the following section, you will find some guidelines to work more efficiently with APIs.

Creating products​

As a vendor​

When you create a product as a vendor, you do not need to specify a vendor ID; the product automatically associates with your company.

With partner role​

If you're creating a product within a partner role, you'll be required to include a vendor ID to identify which company the product will be associated with.

Working with localized content​

When working with localized strings keep the following things in mind:

  • Supported Locales: Ensure you are using a locale that is compatible with your marketplace.
  • Locale tags: Be careful with locale tags for the same language with different regional subtags, or no subtag at all. For example, differentiate between 'en' and 'en-US' or 'fr-FR' and 'fr-CA'.
  • IETF BCP 47: Follow the IETF BCP 47 standard for language tags, incorporating the appropriate regional subtag (e.g., 'en-US', 'fr-FR').

Troubleshooting with userErrors​

You can use (userErrors)[https://d1f7kt971hq16q.cloudfront.net/api/graphql/usererror.doc.html] to obtain more information about issues with an API call.Unlike REST APIs, GraphQL may not include detailed user error messages in the response unless specifically requested. See the example below.

Mutaion​

mutation {
  createProduct(
    input: {
        type: WEB_APP,
        addon: false,
        allowMultiplePurchases: true,
        usageType: MULTI_USER, 
        referable: false, 
        name: [{
            locale: "fr-CA",
            value: "Product Name"}]}
  ) {
    userErrors {
      ... on UnspecifiedVendorError {
        __typename
        path
        message
      }
      ... on InvalidUsageTypeError {
        __typename
        message
        path
        type
        usage
      }
      ... on UnsupportedSupplierIdError {
        __typename
        message
        path
      }
      ... on URLTooLongError {
        __typename
        message
        path
      }
      ... on ProductSupportInvalidEmailAddressError {
        __typename
        message
        path
      }
      ... on ProductSupportInvalidDetailsError {
        __typename
        message
        path
      }
      ... on StringTooLongError {
        __typename
        message
        path
      }
      ... on InvalidMediaSourceError {
        __typename
        message
        path
      }
      ... on MissingDefaultLanguageError {
        __typename
        message
        path
      }
    }
  }
}

Response​

{
  "data": {
    "createProduct": {
      "userErrors": [
        {
          "__typename": "MissingDefaultLanguageError",
          "message": "Product is missing localized value for its default language: \"en-US\"",
          "path": [
            "input",
            "name"
          ]
        }
      ]
    }
  }
}

Authentication scopes​

When you use GraphQL APIs, you need to understand the authentication scopes required for executing specific queries and mutations. Different OAuth2 grant types support different scopes, so you need to ensure that the scope associated with your token matches the requirements for the query or mutation you intend to execute.

You can prevent unnecessary errors by verifying your token's scope alignment with the required scope for your desired query or mutation.

Was this page helpful?

Tell us more…

Help us improve our content. Responses are anonymous.

Thanks

We appreciate your feedback!