Rye Merchant Connectors API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Merchant Connectors API
  version: 1.0.5
  description: 'Turn any product URL into a completed checkout. Instantly retrieve price, tax, and shipping for any product, and let users buy without ever leaving your native AI experience.


    View the [Rye API docs](https://docs.rye.com).'
  termsOfService: https://rye.com/terms-of-service
  license:
    name: UNLICENSED
  contact:
    name: Rye
    email: dev@rye.com
    url: https://docs.rye.com
servers:
- url: https://staging.api.rye.com
tags:
- name: Merchant Connectors
paths:
  /api/v1/merchant-connectors/{connector}/installation-link:
    get:
      operationId: CreateInstallationLink
      responses:
        '200':
          description: OAuth authorization URL for the requested connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantConnectorInstallationLink'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedError'
      description: 'Generate an installation link for a merchant connector (e.g. Shopify).


        The returned URL begins the connector''s OAuth handshake. Direct the

        merchant to it; once they authorize the Rye app, the connector redirects

        back to Rye to complete the install. The merchant is attributed to the

        calling developer and becomes available for checkout via this account.'
      summary: Create merchant connector installation link
      tags:
      - Merchant Connectors
      security:
      - bearerAuth:
        - checkout_intents:write
      parameters:
      - description: The merchant connector to generate an installation link for
        in: path
        name: connector
        required: true
        schema:
          $ref: '#/components/schemas/MerchantConnector'
      - description: Domain or URL of the merchant store to generate the installation link for
        in: query
        name: storeUrl
        required: true
        schema:
          type: string
      - description: If true, the merchant onboarded via this link is exclusive to the calling developer
        in: query
        name: private
        required: false
        schema:
          type: boolean
      x-codeSamples:
      - lang: JavaScript
        source: "import CheckoutIntents from 'checkout-intents';\n\nconst client = new CheckoutIntents({\n  apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted\n});\n\nconst installationLink = await client.merchantConnectors.createInstallationLink('shopify', {\n  storeUrl: 'storeUrl',\n});\n\nconsole.log(installationLink.connector);"
      - lang: Python
        source: "import os\nfrom checkout_intents import CheckoutIntents\n\nclient = CheckoutIntents(\n    api_key=os.environ.get(\"CHECKOUT_INTENTS_API_KEY\"),  # This is the default and can be omitted\n)\ninstallation_link = client.merchant_connectors.create_installation_link(\n    connector=\"shopify\",\n    store_url=\"storeUrl\",\n)\nprint(installation_link.connector)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.merchantconnectors.InstallationLink;\nimport com.rye.models.merchantconnectors.MerchantConnectorCreateInstallationLinkParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        MerchantConnectorCreateInstallationLinkParams params = MerchantConnectorCreateInstallationLinkParams.builder()\n            .connector(MerchantConnectorCreateInstallationLinkParams.Connector.SHOPIFY)\n            .storeUrl(\"storeUrl\")\n            .build();\n        InstallationLink installationLink = client.merchantConnectors().createInstallationLink(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/merchant-connectors/$CONNECTOR/installation-link \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
components:
  schemas:
    NotImplementedError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    ValidateError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
        status:
          type: number
          format: double
        fields:
          $ref: '#/components/schemas/FieldErrors'
      required:
      - name
      - message
      - status
      - fields
      type: object
      additionalProperties: false
    RuntimeError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    MerchantConnectorInstallationLink:
      $ref: '#/components/schemas/ShopifyInstallationLink'
      description: A merchant connector installation link.
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    ShopifyInstallationLink:
      properties:
        url:
          type: string
          description: 'URL to redirect the merchant to in order to install the Rye app on

            their merchant platform.'
        connector:
          type: string
          enum:
          - shopify
          nullable: false
          description: The merchant connector this installation link was generated for.
      required:
      - url
      - connector
      type: object
    MerchantConnector:
      type: string
      enum:
      - shopify
      nullable: false
      description: 'A merchant connector is a Rye integration with a third-party merchant

        platform (e.g. Shopify) that lets developers onboard merchants to Rye.

        Today only Shopify is supported; this union expands as we add support

        for additional connectors (Woocommerce, BigCommerce, etc.).'
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Rye API key