Hang

Hang Partner API

The Hang Partner API lets you power a loyalty program: create and manage program memberships, record point-earning activities, run quests/challenges/puzzles, grant and open loot boxes, manage rewards, redemptions and balance cards, administer programs, tiers, segments and promotions, and reconcile members in bulk. Auth is a per-program API key sent in the X-API-Key header; write operations accept an idempotency_key. Toast and Square POS integrations and real-time webhooks are included.

GitHub OpenAPI

Documentation

📖
APIReference
https://app.swaggerhub.com/apis/Hang.xyz/hang_partner_api/2023.09.07
📖
Documentation
https://docs.hang.com/hang-platform

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hang/refs/heads/main/openapi/hang-partner-api-openapi.yml

Other Resources

🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/hang/refs/heads/main/apis.yml

OpenAPI Specification

hang-partner-api-openapi.yml Raw ↑ 
swagger: '2.0'
info:
  title: Hang Partner API (params in:formData)
  description: |-

    <p>The Partner API allows you to request various resources that can power your loyalty program.</p>
    &copy Hang 2023
  version: 2023.09.07
  x-copyright: '&copy Hang 2023'
basePath: /partner-api

consumes:
  - application/x-www-form-urlencoded
  - multipart/form-data
paths:
  /v2/program-memberships/{program_membership_id}/activities:
    post:
      tags:
        - Activities
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships_program_membership_id_activities
      summary: Create a new activity.
      parameters:
        - name: activity[transaction_timestamp]
          type: number
          in: formData
          required: true
        - name: activity[value]
          type: string
          in: formData
          required: true
        - name: activity[activity_type_id]
          type: string
          in: formData
          required: true
        - name: idempotency_key
          type: string
          in: formData
          required: true
          description: used to prevent double-processing
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
        - name: activity[line_items]
          type: array
          items:
            type: string
          in: formData
      responses:
        '200':
          description: Activity recorded for post-processing
          schema:
            type: object
            properties:
              idempotency_key:
                type: string
                description: idempotency key sent for activity
            additionalProperties: false
            required:
              - idempotency_key
      description: ''
  /v2/program-memberships/{program_membership_id}/activies/synchronous:
    post:
      tags:
        - Activities
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships_program_membership_id_activies_synchronous
      summary: Create a new activity synchronously.
      parameters:
        - name: activity[transaction_timestamp]
          type: number
          in: formData
          required: true
        - name: activity[value]
          type: string
          in: formData
          required: true
        - name: activity[activity_type_id]
          type: string
          in: formData
          required: true
        - name: idempotency_key
          type: string
          in: formData
          required: true
          description: used to prevent double-processing
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
        - name: activity[line_items]
          type: array
          items:
            type: string
          in: formData
      responses:
        '200':
          description: Activity recorded for post-processing
          schema:
            type: object
            properties:
              idempotency_key:
                type: string
                description: idempotency key sent for activity
            additionalProperties: false
            required:
              - idempotency_key
      description: ''
  /v2/program-memberships:
    post:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships
      summary: Creates a new membership with a given wallet_address, external_user_id, or both.
      parameters:
        - name: external_user_id
          type: string
          in: formData
          description: the user's external_user_id (must be provided if wallet_address is blank)
        - name: wallet_address
          type: string
          in: formData
          description: the user's wallet_address (must be provided if external_user_id is blank)
        - name: email
          type: string
          in: formData
          description: the user's email address
      responses:
        '200':
          description: Membership was created successfully, or an existing membership was found
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
        '400':
          description: Missing required parameters.
      description: Invoke this endpoint to add a new membership to your loyalty program.
  /membership/{program_membership_id}/social-media-credentials:
    post:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_membership_program_membership_id_social-media-credentials
      summary: updates membership with social media credentials
      parameters:
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: program membership id
        - name: twitter_username
          type: string
          in: formData
          description: twitter handle associated with the program membership
        - name: instagram_username
          type: string
          in: formData
          description: instagram username associated with the program membership
      responses:
        '200':
          description: Membership was updated with social media credentials
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: ''
  /membership/{program_membership_id}:
    get:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_membership_program_membership_id
      summary: gets membership with social media credentials
      parameters:
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: program membership id
      responses:
        '200':
          description: Membership was retrieved successfully
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: ''
  /membership/wallets/{wallet_address}:
    get:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_membership_wallets_wallet_address
      summary: gets membership with social media credentials from wallet address
      parameters:
        - name: wallet_address
          type: string
          in: path
          required: true
          description: user's wallet address
      responses:
        '200':
          description: Membership was retrieved successfully
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: ''
  /v2/program-memberships/{program_membership_id}/add-trait:
    post:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships_program_membership_id_add-trait
      summary: Endpoint to add a trait to a program membership
      parameters:
        - name: trait_value
          type: string
          in: formData
          required: true
          description: value of the trait
        - name: trait_name
          type: string
          in: formData
          required: true
          description: name of the trait
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              traits:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: trait name
                    value:
                      type: string
                      description: trait value
                  additionalProperties: false
                  required:
                    - name
                    - value
            additionalProperties: false
            required:
              - traits
      description: ''
  /v2/program-memberships/{program_membership_id}/remove-trait:
    post:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships_program_membership_id_remove-trait
      summary: Endpoint to remove a trait from a program membership
      parameters:
        - name: trait_value
          type: string
          in: formData
          required: true
          description: value of the trait
        - name: trait_name
          type: string
          in: formData
          required: true
          description: name of the trait
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              traits:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: trait name
                    value:
                      type: string
                      description: trait value
                  additionalProperties: false
                  required:
                    - name
                    - value
            additionalProperties: false
            required:
              - traits
      description: ''
  /v2/program-memberships/{program_membership_id}/set-image:
    post:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: post_v2_program-memberships_program_membership_id_set-image
      summary: Endpoint to set an image for a program membership
      parameters:
        - name: image_url
          type: string
          in: formData
          required: true
          description: url of the image
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: ''
  /v2/program-memberships/{program_membership_id}:
    patch:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: patch_v2_program-memberships_program_membership_id
      summary: Endpoint to update a program membership with a wallet_address, on_chain_token_id, and/or external_user_id
      parameters:
        - name: program_membership_id
          type: number
          in: path
          required: true
        - name: wallet_address
          type: string
          in: formData
          description: the wallet address to update the program membership with
        - name: on_chain_token_id
          type: string
          in: formData
          description: the on chain token id to update the program membership with
        - name: external_user_id
          type: string
          in: formData
          description: the external user id to update the program membership with
      responses:
        '200':
          description: Membership was updated with provided wallet_address, on_chain_token_id, and/or external_user_id
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: Sets a wallet_address, on_chain_token_id, and/or external_user_id on the specified program_membership.
  /v2/program-memberships/search:
    get:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_v2_program-memberships_search
      summary: Endpoint to find a program membership by external_user_id
      parameters:
        - name: external_user_id
          type: string
          in: query
          description: the external user id to update the program membership with
      responses:
        '200':
          description: Membership was found with provided wallet_address, on_chain_token_id, and/or external_user_id
          schema:
            type: object
            properties:
              membership:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the membership
                  external_user_id:
                    type: string
                    description: The external user id for the membership
                  wallet_address:
                    type: string
                    description: The wallet address for the membership
                  on_chain_token_id:
                    type: string
                    description: The on chain token id for the membership
                  created_at:
                    type: number
                    description: When the membership was created, in epoch seconds.
                  social_media_credentials:
                    type: object
                    properties:
                      twitter_username:
                        type: string
                        description: The instagram handle for the membership
                      instagram_username:
                        type: string
                        description: The instagram handle for the membership
                      tiktok_username:
                        type: string
                        description: The tiktok username associated with the membership
                    additionalProperties: false
                    required:
                      - twitter_username
                      - instagram_username
                      - tiktok_username
                additionalProperties: false
                required:
                  - id
                  - external_user_id
                  - wallet_address
                  - on_chain_token_id
                  - created_at
            additionalProperties: false
            required:
              - membership
      description: Finds a program membership by external_user_id.
  /v2/program-memberships/{program_membership_id}/level:
    get:
      tags:
        - Memberships
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_v2_program-memberships_program_membership_id_level
      summary: Retrieve the current level or tier, as well as earned points (XP) for a program membership.
      parameters:
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
      responses:
        '200':
          description: Returns details successfully
          schema:
            type: object
            properties:
              level:
                type: object
                properties:
                  tier:
                    type: string
                    description: Tier name
                  balance:
                    type: number
                    description: XP balance
                additionalProperties: false
                required:
                  - tier
                  - balance
            additionalProperties: false
            required:
              - level
        '404':
          description: Could not find the program membership provided.
      description: Invoke this endpoint to return the tier and earned points (XP) for a given program membership id.
  /programs/tiers:
    get:
      tags:
        - Programs
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_programs_tiers
      summary: Fetch all tiers and corresponding benefits for the program linked to the API key used in the request.
      parameters: []
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              tiers:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique identifier for the program tier object.
                    order:
                      type: number
                      description: The order in which the tier should be displayed.
                    tier_metric_minimum_threshold:
                      type: number
                      description: The minimum amount of points, or any tier metric (e.g. xp, points, stars, etc), the user must reach before being able to unlock the tier.
                    display_name:
                      type: string
                      description: The name of the tier.
                    marketing_benefit_text:
                      type: string
                      description: The marketing benefit text of the tier.
                    image_url:
                      type: string
                      description: The image associated to the tier.
                    benefits:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier for the tier benefit object.
                        order:
                          type: string
                          description: The order in which the tier benefit should be displayed.
                        text:
                          type: string
                          description: The text of the tier benefit.
                        short_text:
                          type: string
                          description: The short text of the tier benefit.
                      additionalProperties: false
                      required:
                        - id
                        - order
                        - text
                        - short_text
                  additionalProperties: false
                  required:
                    - id
                    - order
                    - tier_metric_minimum_threshold
                    - display_name
                    - marketing_benefit_text
                    - image_url
                    - benefits
            additionalProperties: false
            required:
              - tiers
        '500':
          description: Something unexpected happened while trying to retrive the tier benefits.
      description: Tiers represent a status level that a user can achieve based on their activity within a loyalty program. Each tier has a minimum threshold that a user must reach before being able to unlock the tier.
  /v2/admin/program:
    get:
      tags:
        - Programs
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_v2_admin_program
      summary: Endpoint to return program information using the current JWT.
      parameters: []
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              program:
                type: object
                properties:
                  should_use_progression_v2:
                    type: boolean
                    description: Boolean flag indicating if the program is using v2 progression.
                additionalProperties: false
                required:
                  - should_use_progression_v2
            additionalProperties: false
            required:
              - program
      description: ''
  /v2/program-memberships/{program_membership_id}/quests/opt-ins:
    get:
      tags:
        - Quests
      consumes:
        - application/x-www-form-urlencoded
        - multipart/form-data
      operationId: get_v2_program-memberships_program_membership_id_quests_opt-ins
      summary: Endpoint to retrieve all optIns for a program membership
      parameters:
        - name: program_membership_id
          type: string
          in: path
          required: true
          description: the program membership id
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              opt_ins:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique identifier for the OptIn object.
                    quest_id:
                      type: string
                      description: Unique identifier for the Quest object associated with this OptIn.
                    created_at:
                      type: number
                      description: When the OptIn was created, in epoch seconds.
                    updated_at:
                      type: number
                  

# --- truncated at 32 KB (279 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hang/refs/heads/main/openapi/hang-partner-api-openapi.yml